| blob | 48b0e7d0dadd2f034305ca8037f53a3c4e88e787 |
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
176 "Return values
177 If the function succeeds, t is returned.
178 If the function fails, nil is returned.
180 The glfwInit function initializes GLFW. No other GLFW functions may be used before this function
181 has been called.
183 Notes
184 This function may take several seconds to complete on some systems, while on other systems it may
188 "The function terminates GLFW. Among other things it closes the window, if it is opened, and kills any
194 "Return values
195 The function returns the major and minor version numbers and the revision for the currently linked
199 "Call glfw:init, execute forms and clean-up with glfw:terminate once finished.
200 This makes a nice wrapper to an application higher-level form.
201 Signals an error on failure to initialize. Wrapped in a block named glfw:with-init."
217 "width
218 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
219 not zero. If both width and height are zero, then width will be set to 640.
220 height
221 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
222 not zero. If both width and height are zero, then height will be set to 480.
223 redbits, greenbits, bluebits
224 The number of bits to use for each color component of the color buffer (0 means default color
225 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
226 buffer, if possible.
227 alphabits
228 The number of bits to use for the alpha buffer (0 means no alpha buffer).
229 depthbits
230 The number of bits to use for the depth buffer (0 means no depth buffer).
231 stencilbits
232 The number of bits to use for the stencil buffer (0 means no stencil buffer).
233 mode
234 Selects which type of OpenGL window to use. mode can be either +WINDOW+, which
235 will generate a normal desktop window, or +FULLSCREEN+ which will generate a
236 window which covers the entire screen. When +FULLSCREEN+ is selected, the video
237 mode will be changed to the resolution that closest matches the width and height parameters.
239 Return values
240 If the function succeeds, t is returned.
241 If the function fails, nil is returned.
243 Description
245 The function opens a window that best matches the parameters given to
246 the function. How well the resulting window matches the desired window
247 depends mostly on the available hardware and OpenGL drivers. In
248 general, selecting a fullscreen mode has better chances of generating
249 a close match than does a normal desktop window, since GLFW can freely
250 select from all the available video modes. A desktop window is
251 normally restricted to the video mode of the desktop.
253 Notes
255 For additional control of window properties, see glfw::OpenWindowHint.
256 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
257 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
258 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
259 +MOUSE_CURSOR+
260 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
261 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
262 "
267 "target
268 Can be any of the constants in the table 3.1.
269 hint
270 An integer giving the value of the corresponding target (see table 3.1).
272 Description
273 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
274 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
275 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
276 corresponding window properties, and then all hints are reset to their default values.
278 Notes
279 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
280 window has been opened).
281 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
282 pixel formats / visuals are available, glfw::OpenWindow will fail.
283 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
284 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
285 override these settings, which can result in suboptimal operation. The monitor may be unable to display
286 the resulting video signal, or in the worst case it may even be damaged!
296 "Wraps forms such that there is an open window for them to execute in and cleans up the
297 window afterwards. An error is signalled if there was an error opening the window.
298 Takes the same parameters as open-window, with the addition of 'title' which will
299 set the window title after opening.
300 Wrapped in a block named glfw:with-open-window."
301 `(if (%open-window ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
314 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
316 (with-open-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
324 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
325 setting the title given,
326 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
327 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
328 If the window is closed, the loop is also exited."
329 `(with-init-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
330 ,@setup-forms
332 ,@forms
338 "Parameters
339 cbfun
340 Pointer to a callback function that will be called when a user requests that the window should be
341 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
342 window under Microsoft Windows). The function should have the following C language
343 prototype:
344 int GLFWCALL functionname( void );
345 Where functionname is the name of the callback function. The return value of the callback
346 function indicates wether or not the window close action should continue. If the function returns
347 GL_TRUE, the window will be closed. If the function returns GL_FALSE, the window will not
348 be closed.
349 If cbfun is NULL, any previously selected callback function will be deselected.
351 If you declare your callback as returning glfw:boolean, you can use t and nil as return types.
353 Description
354 The function selects which function to be called upon a window close event.
355 A window has to be opened for this function to have any effect.
357 Notes
358 Window close events are recorded continuously, but only reported when glfwPollEvents,
359 glfwWaitEvents or glfwSwapBuffers is called.
360 The OpenGL context is still valid when this function is called.
361 Note that the window close callback function is not called when glfwCloseWindow is called, but only
362 when the close request comes from the window manager.
363 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
364 GL_TRUE from the function.
368 "Parameters
369 title
370 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
372 Description
373 The function changes the title of the opened window.
375 Notes
376 The title property of a window is often used in situations other
377 than for the window title, such as the title of an application icon
381 "Parameters
382 width
383 Width of the window.
384 height
385 Height of the window.
386 Return values
387 none
388 Description
390 The function changes the size of an opened window. The width and
391 height parameters denote the size of the client area of the
392 window (i.e. excluding any window borders and decorations). If the
393 window is in fullscreen mode, the video mode will be changed to a
394 resolution that closest matches the width and height parameters (the
395 number of color bits will not be changed).
397 Notes
399 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
400 video mode is changed.
404 "Parameters
405 x
406 Horizontal position of the window, relative to the upper left corner of the desktop.
407 y
408 Vertical position of the window, relative to the upper left corner of the desktop.
409 Return values
410 none
411 Description
412 The function changes the position of an opened window. It does not have any effect on a fullscreen
413 window.
418 "The function is used for determining the size of an opened window. The returned values are dimensions
419 of the client area of the window (i.e. excluding any window borders and decorations).
420 (list width height)"
428 "Parameters
429 cbfun
430 Pointer to a callback function that will be called every time the window size changes. The
431 function should have the following C language prototype:
432 void GLFWCALL functionname( int width, int height );
433 Where functionname is the name of the callback function, and width and height are the
434 dimensions of the window client area.
435 If cbfun is NULL, any previously selected callback function will be deselected.
436 Return values
437 none
438 Description
439 The function selects which function to be called upon a window size change event.
440 A window has to be opened for this function to have any effect.
441 Notes
442 Window size changes are recorded continuously, but only reported when glfwPollEvents,
446 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
449 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
453 "Parameters
454 param
455 A token selecting which parameter the function should return (see table 3.2).
457 Return values
459 The function returns different parameters depending on the value of
460 param. Table 3.2 lists valid param values, and their corresponding
461 return values.
463 Description
464 The function is used for acquiring various properties of an opened window.
466 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
467 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
468 the OpenGL renderer is a 3rd party renderer, rather than the fallback
469 Microsoft software OpenGL renderer. In other words, it is not a real
470 guarantee that the OpenGL renderer is actually hardware accelerated.
474 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
475 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
479 "Parameters
480 interval
481 Minimum number of monitor vertical retraces between each buffer swap performed by
482 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
483 refresh of the monitor (also known as VSync off).
485 Description
487 The function selects the minimum number of monitor vertical retraces
488 that should occur between two buffer swaps. If the selected swap
489 interval is one, the rate of buffer swaps will never be higher than
490 the vertical refresh rate of the monitor. If the selected swap
491 interval is zero, the rate of buffer swaps is only limited by the
492 speed of the software and the hardware.
494 Notes
496 This function will only have an effect on hardware and drivers that
500 (defcfun+doc ("glfwSetWindowRefreshCallback" set-window-refresh-callback) :void ((cbfun :pointer))
501 "Parameters
502 cbfun
503 Pointer to a callback function that will be called when the window client area needs to be
504 refreshed. The function should have the following CFFI prototype:
505 (cffi:defcallback callback-name :void ((width :int) (height :int)) .. body ..)
506 Where callback is the name of the callback function.
507 If cbfun is the null-pointer, any previously selected callback function will be deselected.
509 Description
511 The function selects which function to be called upon a window refresh
512 event, which occurs when any part of the window client area has been
513 damaged, and needs to be repainted (for instance, if a part of the
514 window that was previously occluded by another window has become
515 visible). A window has to be opened for this function to have any
516 effect.
518 Notes
519 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
520 glfwWaitEvents or glfwSwapBuffers is called.
533 "Parameters
534 maxcount
535 Maximum number of video modes that list vector can hold.
537 Return values
538 The function returns the number of detected video modes (this number will never exceed maxcount).
539 The list vector is filled out with the video modes that are supported by the system.
541 Description
542 The function returns a list of supported video modes. Each video mode is represented by a
543 list of the form:
544 (width height redbits greenbits bluebits)
546 Notes
547 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
548 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
553 collecting
563 "Parameters
564 mode
565 Pointer to a GLFWvidmode structure, which will be filled out by the function.
566 Return values
567 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
568 Description
569 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
570 for a definition of the GLFWvidmode structure.
571 Notes
572 The color depth of the desktop display is always reported as the number of bits for each individual color
573 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
574 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
575 adds up to 8 bits in total.
576 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
577 differ from the desktop video mode if the GLFW window is a fullscreen window).
578 "
588 "Description
589 The function is used for polling for events, such as user input and window resize events. Upon calling
590 this function, all window states, keyboard states and mouse states are updated. If any related callback
591 functions are registered, these are called during the call to glfwPollEvents.
593 Notes
594 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
595 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
596 no need to call glfwPollEvents.
600 "Description
601 The function is used for waiting for events, such as user input and window resize events. Upon calling
602 this function, the calling thread will be put to sleep until any event appears in the event queue. When
603 events are ready, the events will be processed just as they are processed by glfwPollEvents.
604 If there are any events in the queue when the function is called, the function will behave exactly like
605 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
607 Notes
608 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
609 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
610 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
611 assumptions about when or why glfw::WaitEvents will return.
615 "Parameters
616 key
617 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
618 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
619 identifiers.
620 Return values
621 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
622 held down.
624 Description
625 The function queries the current state of a specific keyboard key. The physical location of each key
626 depends on the system keyboard layout setting.
628 Notes
629 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
630 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
631 layouts, they may not be available on other keyboard layouts.
632 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
633 control), the left version is used (e.g. +KEY_LSHIFT+)
634 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
635 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
636 glfw::GetKey.
640 "Parameters
641 button
642 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
643 Return values
644 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
645 mouse button is not held down.
646 Description
647 The function queries the current state of a specific mouse button.
648 Notes
649 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
650 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
651 glfw::GetMouseButton.
652 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
653 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
654 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
659 "Return values
660 The function returns the current mouse position in xpos and ypos.
662 Description
663 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
664 cursor position, relative to the upper left corner of the window and limited to the client area of the
665 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
666 boundaries except to those implied by the maximum number that can be represented by a signed integer
667 (normally -2147483648 to +2147483647).
669 Notes
670 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
671 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
672 glfw::GetMousePos.
677 "Parameters
678 xpos
679 Horizontal position of the mouse.
680 ypos
681 Vertical position of the mouse.
683 Description
684 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
685 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
686 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
690 "Return values
691 The function returns the current mouse wheel position.
692 Description
693 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
694 mouse axis, which is available as a separate wheel or up/down stick on some mice.
695 Notes
696 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
697 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
698 glfw::GetMouseWheel.
702 "Parameters
703 pos
704 Position of the mouse wheel.
705 Description
706 The function changes the position of the mouse wheel.
711 "Parameters
712 cbfun
713 Pointer to a callback function that will be called every time a key is pressed or released. The
714 function should have the following C language prototype:
715 void GLFWCALL functionname( int key, int action );
716 Where functionname is the name of the callback function, key is a key identifier, which is an
717 uppercase printable ISO 8859-1 character or a special key identifier (see table 3.3), and action is
718 either +PRESS+ or +RELEASE+
719 If cbfun is NULL, any previously selected callback function will be deselected.
720 Return values
721 none
722 Description
723 The function selects which function to be called upon a keyboard key event. The callback function is
724 called every time the state of a single key is changed (from released to pressed or vice versa). The
725 reported keys are unaffected by any modifiers (such as shift or alt).
726 A window has to be opened for this function to have any effect.
727 Notes
728 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
729 or glfw::SwapBuffers is called.
732 "Parameters
733 cbfun
734 Pointer to a callback function that will be called every time a printable character is generated by
735 the keyboard. The function should have the following C language prototype:
736 void GLFWCALL functionname( int character, int action );
737 Where functionname is the name of the callback function, character is a Unicode (ISO 10646)
738 character, and action is either +PRESS+ or +RELEASE+
739 If cbfun is NULL, any previously selected callback function will be deselected.
740 Return values
741 none
742 Description
743 The function selects which function to be called upon a keyboard character event. The callback function
744 is called every time a key that results in a printable Unicode character is pressed or released. Characters
745 are affected by modifiers (such as shift or alt).
746 A window has to be opened for this function to have any effect.
747 Notes
748 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
749 or glfw::SwapBuffers is called.
750 Control characters, such as tab and carriage return, are not reported to the character callback function,
751 since they are not part of the Unicode character set. Use the key callback function for such events (see
752 glfw::SetKeyCallback).
753 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
754 eight bit data type (e.g. the C language char type) without first checking that the character code is less
755 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
758 "Parameters
759 cbfun
760 Pointer to a callback function that will be called every time a mouse button is pressed or released.
761 The function should have the following C language prototype:
762 void GLFWCALL functionname( int button, int action );
763 Where functionname is the name of the callback function, button is a mouse button identifier (see
764 table 3.4 on page 56), and action is either +PRESS+ or +RELEASE+
765 If cbfun is NULL, any previously selected callback function will be deselected.
766 Return values
767 none
768 Description
769 The function selects which function to be called upon a mouse button event.
770 A window has to be opened for this function to have any effect.
771 Notes
772 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
773 glfw::WaitEvents or glfw::SwapBuffers is called.
774 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
775 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
776 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
779 "Parameters
780 cbfun
781 Pointer to a callback function that will be called every time the mouse is moved. The function
782 should have the following C language prototype:
783 void GLFWCALL functionname( int x, int y );
784 Where functionname is the name of the callback function, and x and y are the mouse coordinates
785 (see glfw::GetMousePos for more information on mouse coordinates).
786 If cbfun is NULL, any previously selected callback function will be deselected.
787 Return values
788 none
789 Description
790 The function selects which function to be called upon a mouse motion event.
791 A window has to be opened for this function to have any effect.
792 Notes
793 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
794 glfw::WaitEvents or glfw::SwapBuffers is called.
797 "Parameters
798 cbfun
799 Pointer to a callback function that will be called every time the mouse wheel is moved. The
800 function should have the following C language prototype:
801 void GLFWCALL functionname( int pos );
802 Where functionname is the name of the callback function, and pos is the mouse wheel position.
803 If cbfun is NULL, any previously selected callback function will be deselected.
804 Return values
805 none
806 Description
807 The function selects which function to be called upon a mouse wheel event.
808 A window has to be opened for this function to have any effect.
809 Notes
810 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
811 glfw::WaitEvents or glfw::SwapBuffers is called.
815 "Parameters
816 joy
817 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
818 param
819 A token selecting which parameter the function should return (see table 3.5).
820 Return values
821 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
822 values, and their corresponding return values.
823 Description
824 The function is used for acquiring various properties of a joystick.
825 Notes
826 The joystick information is updated every time the function is called.
827 No window has to be opened for joystick information to be valid.
830 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
833 "Parameters
834 joy
835 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
836 numaxes
837 Specifies how many axes should be returned.
838 Return values
839 An list that will hold the positional values for all requested axes.
840 If the joystick is not supported or connected, the function will
841 return nil.
843 Description
844 The function queries the current position of one or more axes of a joystick. The positional values are
845 returned in an array, where the first element represents the first axis of the joystick (normally the X
846 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
847 right, forward or up, and the negative direction is left, back or down.
848 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
849 unused elements in the pos array will be set to 0.0 (zero).
851 Notes
852 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
853 or glfw::WaitEvents for joystick state to be updated.
854 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
855 supported axes.
856 No window has to be opened for joystick input to be valid.
857 "
863 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
865 "Parameters
866 joy
867 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
868 numbuttons
869 Specifies how many buttons should be returned.
870 Return values
871 A list that will hold the button states for all requested buttons.
872 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
873 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
874 function will return 0 (zero).
876 Description
877 The function queries the current state of one or more buttons of a joystick. The button states are
878 returned in an array, where the first element represents the first button of the joystick. Each state can be
879 either +PRESS+ or +RELEASE+
880 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
881 available, the unused elements in the buttons array will be set to +RELEASE+
883 Notes
884 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
885 or glfw::WaitEvents for joystick state to be updated.
886 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
887 supported buttons.
888 No window has to be opened for joystick input to be valid.
889 "
896 "Return values
897 The function returns the value of the high precision timer. The time is measured in seconds, and is
898 returned as a double precision floating point value.
900 Description
901 The function returns the state of a high precision timer. Unless the timer has been set by the
902 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
903 was called.
905 Notes
906 The resolution of the timer depends on which system the program is running on. The worst case
907 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
908 than 1us.
912 "Parameters
913 time
914 Time (in seconds) that the timer should be set to.
916 Description
917 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
918 glfw::GetTime will be relative to this time. The time is given in seconds.
922 "Parameters
923 time
924 Time, in seconds, to sleep.
926 Description
927 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
928 put to sleep. Other threads within the same process can still execute.
930 Notes
931 There is usually a system dependent minimum time for which it is possible to sleep. This time is
932 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
933 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
934 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
946 "Parameters
947 name
948 A null terminated ISO 8859-1 string holding the name of the file that should be read.
949 img
950 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
951 read was successful).
952 flags
953 Flags for controlling the image reading process. Valid flags are listed in table 3.6
954 Return values
955 The function returns t if the image was loaded successfully. Otherwise nil is
956 returned.
957 Description
958 The function reads an image from the file specified by the parameter name and returns the image
959 information and data in a GLFWimage structure, which has the following definition:
961 typedef struct {
962 int Width, Height; // Image dimensions
963 int Format; // OpenGL pixel format
964 int BytesPerPixel; // Number of bytes per pixel
965 unsigned char *Data; // Pointer to pixel data
966 } GLFWimage;
968 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
969 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
970 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
972 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
973 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
974 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
975 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
976 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
977 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
979 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
980 Notes
981 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
982 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
983 Paletted images are translated into true color or true color + alpha pixel formats.
984 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
985 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
990 "Parameters
991 data
992 The memory buffer holding the contents of the file that should be read.
993 size
994 The size, in bytes, of the memory buffer.
995 img
996 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
997 read was successful).
998 flags
999 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1000 Return values
1001 The function returns t if the image was loaded successfully. Otherwise nil is
1002 returned.
1003 Description
1004 The function reads an image from the memory buffer specified by the parameter data and returns the
1005 image information and data in a GLFWimage structure, which has the following definition:
1007 typedef struct {
1008 int Width, Height; // Image dimensions
1009 int Format; // OpenGL pixel format
1010 int BytesPerPixel; // Number of bytes per pixel
1011 unsigned char *Data; // Pointer to pixel data
1012 } GLFWimage;
1014 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1015 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1016 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1018 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1019 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1020 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1021 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1022 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1023 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1024 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1025 Notes
1026 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1027 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1028 alpha.
1029 Paletted images are translated into true color or true color + alpha pixel formats.
1030 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1031 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1035 "Parameters
1036 img
1037 Pointer to a GLFWimage struct.
1038 Description
1039 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1040 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1044 "Parameters
1045 name
1046 An ISO 8859-1 string holding the name of the file that should be loaded.
1047 flags
1048 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1049 Return values
1050 The function returns t if the texture was loaded successfully. Otherwise nil is
1051 returned.
1053 Description
1055 The function reads an image from the file specified by the parameter
1056 name and uploads the image to OpenGL texture memory (using the
1057 glTexImage2D function). If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1058 all mipmap levels for the loaded texture are generated and uploaded to
1059 texture memory. Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1060 the texture is the lower left corner of the loaded image. If the flag
1061 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1062 corner. For single component images (i.e. gray scale), the texture is
1063 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1064 otherwise it is uploaded as a luminance texture.
1066 Notes
1067 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1068 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1069 alpha.
1070 Paletted images are translated into true color or true color + alpha pixel formats.
1071 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1072 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1073 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1074 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1075 generated by GLFW in software.
1077 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1078 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1079 texture is a single component texture. The red, green and blue components are set to 1.0.
1084 "Parameters
1085 data
1086 The memory buffer holding the contents of the file that should be loaded.
1087 size
1088 The size, in bytes, of the memory buffer.
1089 flags
1090 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1091 Return values
1092 The function returns t if the texture was loaded successfully. Otherwise nil is
1093 returned.
1095 Description
1096 The function reads an image from the memory buffer specified by the parameter data and uploads the
1097 image to OpenGL texture memory (using the glTexImage2D function).
1098 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1099 generated and uploaded to texture memory.
1100 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1101 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1102 corner.
1103 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1104 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1106 Notes
1107 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1108 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1109 + alpha.
1110 Paletted images are translated into true color or true color + alpha pixel formats.
1111 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1112 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1113 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1114 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1115 generated by GLFW in software.
1117 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1118 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1119 texture is a single component texture. The red, green and blue components are set to 1.0.
1125 "Parameters
1126 img
1127 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1128 flags
1129 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1130 Return values
1131 The function returns t if the texture was loaded successfully. Otherwise nil is
1132 returned.
1134 Description
1135 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1136 the glTexImage2D function).
1137 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1138 generated and uploaded to texture memory.
1139 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1140 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1141 corner.
1142 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1143 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1145 Notes
1146 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1147 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1148 + alpha.
1149 Paletted images are translated into true color or true color + alpha pixel formats.
1150 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1151 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1152 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1153 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1154 generated by GLFW in software.
1156 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1157 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1162 "Parameters
1163 extension
1164 A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1165 Return values
1166 The function returns t if the extension is supported. Otherwise it returns nil.
1167 Description
1168 The function does a string search in the list of supported OpenGL extensions to find if the specified
1169 extension is listed.
1170 Notes
1172 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1173 must have been opened with glfwOpenWindow).
1174 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1175 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1176 System.
1180 "Parameters
1181 procname
1182 A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1183 Return values
1184 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1185 NULL is returned.
1186 Description
1187 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1188 extensions define new API functions, which are usually not available through normal linking. It is
1189 therefore necessary to get access to those API functions at runtime.
1190 Notes
1192 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1193 must have been opened with glfwOpenWindow).
1194 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1195 will always return NULL.
1201 "Return values
1202 The function returns the major and minor version numbers and the revision for the currently used
1203 OpenGL implementation as a list (major minor rev).
1205 Description
1206 The function returns the OpenGL implementation version. This is a convenient function that parses
1207 the version number information from the string returned by calling
1208 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1209 what functionality is supported by the used OpenGL implementation.
1211 Notes
1212 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1221 "Parameters
1222 fun
1223 A pointer to a function that acts as the entry point for the new thread. The function should have
1224 the following C language prototype:
1225 void GLFWCALL functionname( void *arg );
1226 Where functionname is the name of the thread function, and arg is the user supplied argument
1227 (see below).
1228 arg
1229 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1230 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1231 Return values
1232 The function returns a thread identification number if the thread was created successfully. This number
1233 is always positive. If the function fails, a negative number is returned.
1234 Description
1235 The function creates a new thread, which executes within the same address space as the calling process.
1236 The thread entry point is specified with the fun argument.
1237 Once the thread function fun returns, the thread dies.
1238 Notes
1239 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1240 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1243 "Parameters
1244 ID
1245 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1246 Description
1247 The function kills a running thread and removes it from the thread list.
1248 Notes
1249 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1250 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1251 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1254 "Parameters
1255 ID
1256 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1257 waitmode
1258 Can be either +WAIT+ or +NOWAIT+
1259 Return values
1260 The function returns t if the specified thread died after the function was called, or the thread
1261 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1262 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1263 running.
1266 "Return values
1267 The function returns a thread identification handle for the calling thread.
1268 Description
1269 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1270 by glfw::CreateThread when the thread was created.
1274 "Return values
1275 The function returns a mutex handle, or NULL if the mutex could not be created.
1276 Description
1277 The function creates a mutex object, which can be used to control access to data that is shared between
1278 threads.
1281 "Parameters
1282 mutex
1283 A mutex object handle.
1284 Description
1285 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1286 used by any thread.
1289 "Parameters
1290 mutex
1291 A mutex object handle.
1292 Description
1293 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1294 thread, the function will block the calling thread until it is released by the locking thread. Once the
1295 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1296 glfw::UnlockMutex.
1299 "Parameters
1300 mutex
1301 A mutex object handle.
1302 Description
1303 The function releases the lock of a locked mutex object.
1307 "Parameters
1308 mutex
1309 A mutex object handle.
1310 forms
1311 Body of code to execute
1312 Description
1313 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1314 using glfw::UnlockMutex.
1315 So, forms will not execute until an exclusive lock is held.
1316 The lock is then released when the stack is unwound."
1324 "Return values
1325 The function returns a condition variable handle, or NULL if the condition variable could not be
1326 created.
1327 Description
1328 The function creates a condition variable object, which can be used to synchronize threads.
1331 "Parameters
1332 cond
1333 A condition variable object handle.
1334 Description
1335 The function destroys a condition variable object. After a condition variable object has been destroyed,
1336 it may no longer be used by any thread.
1339 " arameters
1340 cond
1341 A condition variable object handle.
1342 mutex
1343 A mutex object handle.
1344 timeout
1345 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1346 seconds), or +INFINITY+
1347 Description
1348 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1349 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1350 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1351 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1352 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1353 Notes
1354 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1355 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1356 prepares to wait on a condition variable and another thread signals the condition just before the first
1357 thread actually waits on it.
1360 "Parameters
1361 cond
1362 A condition variable object handle.
1363 Description
1364 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1365 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1366 is not specified which.
1367 Notes
1368 When several threads are waiting for the condition variable, which thread is started depends on
1369 operating system scheduling rules, and may vary from system to system and from time to time.
1372 "Parameters
1373 cond
1374 A condition variable object handle.
1375 Description
1376 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1377 waiting on cond, nothing happens.
1378 Notes
1379 When several threads are waiting for the condition variable, the order in which threads are started
1380 depends on operating system scheduling rules, and may vary from system to system and from time to
1381 time.
1385 "Return values
1386 The function returns the number of active processors in the system.
1387 Description
1388 The function determines the number of active processors in the system.
1389 Notes
1390 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1391 Threading) processors, will report the number of logical processors.
1394 "Parameters
1395 token
1396 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1397 Return values
1398 none
1399 Description
1400 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1401 description of each feature.
1402 +AUTO_POLL_EVENTS+
1403 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1404 that glfw::SwapBuffers is called.
1405 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1406 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1407 function, since calling glfw::PollEvents from a callback function is not allowed.
1408 +KEY_REPEAT+
1409 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1410 when a key is held down long enough (according to the system key repeat configuration).
1411 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1412 when a key is pressed (and once when it is released).
1413 +MOUSE_CURSOR+
1414 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1415 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1416 the client area of the window.
1417 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1418 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1419 from the mouse, without being restricted or manipulated by the windowing system.
1420 +STICKY_KEYS+
1421 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1422 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1423 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1424 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1425 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1426 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1427 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1428 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1429 all keys.
1430 +STICKY_MOUSE_BUTTONS+
1431 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1432 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1433 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1434 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1435 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1436 glfw::GetMouseButton will never be released. Note also that enabling
1437 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1438 functionality.
1439 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1440 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1441 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1442 +SYSTEM_KEYS+
1443 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1444 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1445 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1446 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1447 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1448 the GLFW video mode again.
1449 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1450 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1451 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1454 "Parameters
1455 token
1456 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1457 Return values
1458 none
1459 Description
1460 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1461 description of each feature.
1462 +AUTO_POLL_EVENTS+
1463 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1464 that glfw::SwapBuffers is called.
1465 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1466 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1467 function, since calling glfw::PollEvents from a callback function is not allowed.
1468 +KEY_REPEAT+
1469 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1470 when a key is held down long enough (according to the system key repeat configuration).
1471 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1472 when a key is pressed (and once when it is released).
1473 +MOUSE_CURSOR+
1474 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1475 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1476 the client area of the window.
1477 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1478 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1479 from the mouse, without being restricted or manipulated by the windowing system.
1480 +STICKY_KEYS+
1481 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1482 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1483 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1484 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1485 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1486 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1487 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1488 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1489 all keys.
1490 +STICKY_MOUSE_BUTTONS+
1491 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1492 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1493 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1494 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1495 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1496 glfw::GetMouseButton will never be released. Note also that enabling
1497 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1498 functionality.
1499 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1500 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1501 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1502 +SYSTEM_KEYS+
1503 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1504 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1505 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1506 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1507 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1508 the GLFW video mode again.
1509 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1510 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1511 the GLFW program must not be interrupted (normally for games in fullscreen mode).