| blob | a250bfad18b0c6d32517d8dff80ce5fa06a94687 |
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 than for the window title, such as the title
380 "Parameters
381 width
382 Width of the window.
383 height
384 Height of the window.
385 Return values
386 none
387 Description
388 The function changes the size of an opened window. The width and height parameters denote the size of
389 the client area of the window (i.e. excluding any window borders and decorations).
390 If the window is in fullscreen mode, the video mode will be changed to a resolution that closest matches
391 the width and height parameters (the number of color bits will not be changed).
392 Notes
393 The OpenGL™ context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
394 video mode is changed.
398 "Parameters
399 x
400 Horizontal position of the window, relative to the upper left corner of the desktop.
401 y
402 Vertical position of the window, relative to the upper left corner of the desktop.
403 Return values
404 none
405 Description
406 The function changes the position of an opened window. It does not have any effect on a fullscreen
407 window.
412 "The function is used for determining the size of an opened window. The returned values are dimensions
413 of the client area of the window (i.e. excluding any window borders and decorations).
414 (list width height)"
422 "Parameters
423 cbfun
424 Pointer to a callback function that will be called every time the window size changes. The
425 function should have the following C language prototype:
426 void GLFWCALL functionname( int width, int height );
427 Where functionname is the name of the callback function, and width and height are the
428 dimensions of the window client area.
429 If cbfun is NULL, any previously selected callback function will be deselected.
430 Return values
431 none
432 Description
433 The function selects which function to be called upon a window size change event.
434 A window has to be opened for this function to have any effect.
435 Notes
436 Window size changes are recorded continuously, but only reported when glfwPollEvents,
440 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
443 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
447 "Parameters
448 param
449 A token selecting which parameter the function should return (see table 3.2).
451 Return values
452 The function returns different parameters depending on the value of param. Table 3.2 lists valid param
453 values, and their corresponding return values.
455 Description
456 The function is used for acquiring various properties of an opened window.
458 Notes
459 +ACCELERATED+ is only supported under Windows. Other systems will always return
460 GL::+TRUE+. Under Windows, +ACCELERATED+ means that the OpenGL™ renderer is a 3rd
461 party renderer, rather than the fallback Microsoft software OpenGL™ renderer. In other words, it is
462 not a real guarantee that the OpenGL™ renderer is actually hardware accelerated.
466 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
467 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
471 "Parameters
472 interval
473 Minimum number of monitor vertical retraces between each buffer swap performed by
474 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
475 refresh of the monitor (also known as ’VSync off’).
477 Description
478 The function selects the minimum number of monitor vertical retraces that should occur between two
479 buffer swaps. If the selected swap interval is one, the rate of buffer swaps will never be higher than the
480 vertical refresh rate of the monitor. If the selected swap interval is zero, the rate of buffer swaps is only
481 limited by the speed of the software and the hardware.
483 Notes
484 This function will only have an effect on hardware and drivers that support user selection of the swap
488 (defcfun+doc ("glfwSetWindowRefreshCallback" set-window-refresh-callback) :void ((cbfun :pointer))
489 "Parameters
490 cbfun
491 Pointer to a callback function that will be called when the window client area needs to be
492 refreshed. The function should have the following CFFI prototype:
493 (cffi:defcallback callback-name :void ((width :int) (height :int)) .. body ..)
494 Where callback is the name of the callback function.
495 If cbfun is the null-pointer, any previously selected callback function will be deselected.
497 Description
498 The function selects which function to be called upon a window refresh event, which occurs when any
499 part of the window client area has been damaged, and needs to be repainted (for instance, if a part of the
500 window that was previously occluded by another window has become visible).
501 A window has to be opened for this function to have any effect.
503 Notes
504 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
505 glfwWaitEvents or glfwSwapBuffers is called.
518 "Parameters
519 maxcount
520 Maximum number of video modes that list vector can hold.
522 Return values
523 The function returns the number of detected video modes (this number will never exceed maxcount).
524 The list vector is filled out with the video modes that are supported by the system.
526 Description
527 The function returns a list of supported video modes. Each video mode is represented by a
528 list of the form:
529 (width height redbits greenbits bluebits)
531 Notes
532 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
533 resolution (Width × Height), with the lowest resolution, fewest bits per pixel mode first. "
538 collecting
548 "Parameters
549 mode
550 Pointer to a GLFWvidmode structure, which will be filled out by the function.
551 Return values
552 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
553 Description
554 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
555 for a definition of the GLFWvidmode structure.
556 Notes
557 The color depth of the desktop display is always reported as the number of bits for each individual color
558 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
559 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
560 adds up to 8 bits in total.
561 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
562 differ from the desktop video mode if the GLFW window is a fullscreen window).
563 "
573 "Description
574 The function is used for polling for events, such as user input and window resize events. Upon calling
575 this function, all window states, keyboard states and mouse states are updated. If any related callback
576 functions are registered, these are called during the call to glfwPollEvents.
578 Notes
579 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
580 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
581 no need to call glfwPollEvents.
585 "Description
586 The function is used for waiting for events, such as user input and window resize events. Upon calling
587 this function, the calling thread will be put to sleep until any event appears in the event queue. When
588 events are ready, the events will be processed just as they are processed by glfwPollEvents.
589 If there are any events in the queue when the function is called, the function will behave exactly like
590 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
592 Notes
593 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
594 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
595 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
596 assumptions about when or why glfw::WaitEvents will return.
600 "Parameters
601 key
602 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
603 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
604 identifiers.
605 Return values
606 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
607 held down.
609 Description
610 The function queries the current state of a specific keyboard key. The physical location of each key
611 depends on the system keyboard layout setting.
613 Notes
614 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
615 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
616 layouts, they may not be available on other keyboard layouts.
617 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
618 control), the left version is used (e.g. +KEY_LSHIFT+)
619 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
620 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
621 glfw::GetKey.
625 "Parameters
626 button
627 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
628 Return values
629 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
630 mouse button is not held down.
631 Description
632 The function queries the current state of a specific mouse button.
633 Notes
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 mouse button events are recorded and reported by
636 glfw::GetMouseButton.
637 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
638 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
639 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
644 "Return values
645 The function returns the current mouse position in xpos and ypos.
647 Description
648 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
649 cursor position, relative to the upper left corner of the window and limited to the client area of the
650 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
651 boundaries except to those implied by the maximum number that can be represented by a signed integer
652 (normally -2147483648 to +2147483647).
654 Notes
655 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
656 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
657 glfw::GetMousePos.
662 "Parameters
663 xpos
664 Horizontal position of the mouse.
665 ypos
666 Vertical position of the mouse.
668 Description
669 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
670 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
671 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
675 "Return values
676 The function returns the current mouse wheel position.
677 Description
678 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
679 mouse axis, which is available as a separate wheel or up/down stick on some mice.
680 Notes
681 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
682 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
683 glfw::GetMouseWheel.
687 "Parameters
688 pos
689 Position of the mouse wheel.
690 Description
691 The function changes the position of the mouse wheel.
696 "Parameters
697 cbfun
698 Pointer to a callback function that will be called every time a key is pressed or released. The
699 function should have the following C language prototype:
700 void GLFWCALL functionname( int key, int action );
701 Where functionname is the name of the callback function, key is a key identifier, which is an
702 uppercase printable ISO 8859-1 character or a special key identifier (see table 3.3), and action is
703 either +PRESS+ or +RELEASE+
704 If cbfun is NULL, any previously selected callback function will be deselected.
705 Return values
706 none
707 Description
708 The function selects which function to be called upon a keyboard key event. The callback function is
709 called every time the state of a single key is changed (from released to pressed or vice versa). The
710 reported keys are unaffected by any modifiers (such as shift or alt).
711 A window has to be opened for this function to have any effect.
712 Notes
713 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
714 or glfw::SwapBuffers is called.
717 "Parameters
718 cbfun
719 Pointer to a callback function that will be called every time a printable character is generated by
720 the keyboard. The function should have the following C language prototype:
721 void GLFWCALL functionname( int character, int action );
722 Where functionname is the name of the callback function, character is a Unicode (ISO 10646)
723 character, and action is either +PRESS+ or +RELEASE+
724 If cbfun is NULL, any previously selected callback function will be deselected.
725 Return values
726 none
727 Description
728 The function selects which function to be called upon a keyboard character event. The callback function
729 is called every time a key that results in a printable Unicode character is pressed or released. Characters
730 are affected by modifiers (such as shift or alt).
731 A window has to be opened for this function to have any effect.
732 Notes
733 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
734 or glfw::SwapBuffers is called.
735 Control characters, such as tab and carriage return, are not reported to the character callback function,
736 since they are not part of the Unicode character set. Use the key callback function for such events (see
737 glfw::SetKeyCallback).
738 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
739 eight bit data type (e.g. the C language ’char’ type) without first checking that the character code is less
740 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
743 "Parameters
744 cbfun
745 Pointer to a callback function that will be called every time a mouse button is pressed or released.
746 The function should have the following C language prototype:
747 void GLFWCALL functionname( int button, int action );
748 Where functionname is the name of the callback function, button is a mouse button identifier (see
749 table 3.4 on page 56), and action is either +PRESS+ or +RELEASE+
750 If cbfun is NULL, any previously selected callback function will be deselected.
751 Return values
752 none
753 Description
754 The function selects which function to be called upon a mouse button event.
755 A window has to be opened for this function to have any effect.
756 Notes
757 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
758 glfw::WaitEvents or glfw::SwapBuffers is called.
759 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
760 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
761 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
764 "Parameters
765 cbfun
766 Pointer to a callback function that will be called every time the mouse is moved. The function
767 should have the following C language prototype:
768 void GLFWCALL functionname( int x, int y );
769 Where functionname is the name of the callback function, and x and y are the mouse coordinates
770 (see glfw::GetMousePos for more information on mouse coordinates).
771 If cbfun is NULL, any previously selected callback function will be deselected.
772 Return values
773 none
774 Description
775 The function selects which function to be called upon a mouse motion event.
776 A window has to be opened for this function to have any effect.
777 Notes
778 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
779 glfw::WaitEvents or glfw::SwapBuffers is called.
782 "Parameters
783 cbfun
784 Pointer to a callback function that will be called every time the mouse wheel is moved. The
785 function should have the following C language prototype:
786 void GLFWCALL functionname( int pos );
787 Where functionname is the name of the callback function, and pos is the mouse wheel position.
788 If cbfun is NULL, any previously selected callback function will be deselected.
789 Return values
790 none
791 Description
792 The function selects which function to be called upon a mouse wheel event.
793 A window has to be opened for this function to have any effect.
794 Notes
795 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
796 glfw::WaitEvents or glfw::SwapBuffers is called.
800 "Parameters
801 joy
802 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
803 param
804 A token selecting which parameter the function should return (see table 3.5).
805 Return values
806 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
807 values, and their corresponding return values.
808 Description
809 The function is used for acquiring various properties of a joystick.
810 Notes
811 The joystick information is updated every time the function is called.
812 No window has to be opened for joystick information to be valid.
815 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
818 "Parameters
819 joy
820 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
821 numaxes
822 Specifies how many axes should be returned.
823 Return values
824 An list that will hold the positional values for all requested axes.
825 If the joystick is not supported or connected, the function will
826 return nil.
828 Description
829 The function queries the current position of one or more axes of a joystick. The positional values are
830 returned in an array, where the first element represents the first axis of the joystick (normally the X
831 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
832 right, forward or up, and the negative direction is left, back or down.
833 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
834 unused elements in the pos array will be set to 0.0 (zero).
836 Notes
837 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
838 or glfw::WaitEvents for joystick state to be updated.
839 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
840 supported axes.
841 No window has to be opened for joystick input to be valid.
842 "
848 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
850 "Parameters
851 joy
852 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
853 numbuttons
854 Specifies how many buttons should be returned.
855 Return values
856 A list that will hold the button states for all requested buttons.
857 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
858 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
859 function will return 0 (zero).
861 Description
862 The function queries the current state of one or more buttons of a joystick. The button states are
863 returned in an array, where the first element represents the first button of the joystick. Each state can be
864 either +PRESS+ or +RELEASE+
865 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
866 available, the unused elements in the buttons array will be set to +RELEASE+
868 Notes
869 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
870 or glfw::WaitEvents for joystick state to be updated.
871 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
872 supported buttons.
873 No window has to be opened for joystick input to be valid.
874 "
881 "Return values
882 The function returns the value of the high precision timer. The time is measured in seconds, and is
883 returned as a double precision floating point value.
885 Description
886 The function returns the state of a high precision timer. Unless the timer has been set by the
887 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
888 was called.
890 Notes
891 The resolution of the timer depends on which system the program is running on. The worst case
892 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
893 than 1 μs.
897 "Parameters
898 time
899 Time (in seconds) that the timer should be set to.
901 Description
902 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
903 glfw::GetTime will be relative to this time. The time is given in seconds.
907 "Parameters
908 time
909 Time, in seconds, to sleep.
911 Description
912 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
913 put to sleep. Other threads within the same process can still execute.
915 Notes
916 There is usually a system dependent minimum time for which it is possible to sleep. This time is
917 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
918 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
919 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
931 "Parameters
932 name
933 A null terminated ISO 8859-1 string holding the name of the file that should be read.
934 img
935 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
936 read was successful).
937 flags
938 Flags for controlling the image reading process. Valid flags are listed in table 3.6
939 Return values
940 The function returns t if the image was loaded successfully. Otherwise nil is
941 returned.
942 Description
943 The function reads an image from the file specified by the parameter name and returns the image
944 information and data in a GLFWimage structure, which has the following definition:
945 § ¤
946 typedef struct {
947 int Width, Height; // Image dimensions
948 int Format; // OpenGL pixel format
949 int BytesPerPixel; // Number of bytes per pixel
950 unsigned char *Data; // Pointer to pixel data
951 } GLFWimage;
952 ¦ ¥
953 Width and Height give the dimensions of the image. Format specifies an OpenGL™ pixel format,
954 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
955 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
956 By default the read image is rescaled to the nearest larger 2m × 2n resolution using bilinear
957 interpolation, if necessary, which is useful if the image is to be used as an OpenGL™ texture. This
958 behavior can be disabled by setting the +NO_RESCALE_BIT+ flag.
959 Unless the flag +ORIGIN_UL_BIT+ is set, the first pixel in img->Data is the lower left corner of
960 the image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left corner.
961 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
962 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
963 Notes
964 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
965 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
966 Paletted images are translated into true color or true color + alpha pixel formats.
967 Please note that OpenGL™ 1.0 does not support single component alpha maps, so do not use images
968 with Format = GL_ALPHA directly as textures under OpenGL™ 1.0.
973 "Parameters
974 data
975 The memory buffer holding the contents of the file that should be read.
976 size
977 The size, in bytes, of the memory buffer.
978 img
979 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
980 read was successful).
981 flags
982 Flags for controlling the image reading process. Valid flags are listed in table 3.6
983 Return values
984 The function returns t if the image was loaded successfully. Otherwise nil is
985 returned.
986 Description
987 The function reads an image from the memory buffer specified by the parameter data and returns the
988 image information and data in a GLFWimage structure, which has the following definition:
989 § ¤
990 typedef struct {
991 int Width, Height; // Image dimensions
992 int Format; // OpenGL pixel format
993 int BytesPerPixel; // Number of bytes per pixel
994 unsigned char *Data; // Pointer to pixel data
995 } GLFWimage;
996 ¦ ¥
997 Width and Height give the dimensions of the image. Format specifies an OpenGL™ pixel format,
998 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
999 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1000 By default the read image is rescaled to the nearest larger 2m × 2n resolution using bilinear
1001 interpolation, if necessary, which is useful if the image is to be used as an OpenGL™ texture. This
1002 behavior can be disabled by setting the +NO_RESCALE_BIT+ flag.
1003 Unless the flag +ORIGIN_UL_BIT+ is set, the first pixel in img->Data is the lower left corner of
1004 the image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left corner.
1005 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1006 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1007 Notes
1008 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1009 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1010 alpha.
1011 Paletted images are translated into true color or true color + alpha pixel formats.
1012 Please note that OpenGL™ 1.0 does not support single component alpha maps, so do not use images
1013 with Format = GL_ALPHA directly as textures under OpenGL™ 1.0.
1017 "Parameters
1018 img
1019 Pointer to a GLFWimage struct.
1020 Description
1021 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1022 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1026 "Parameters
1027 name
1028 An ISO 8859-1 string holding the name of the file that should be loaded.
1029 flags
1030 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1031 Return values
1032 The function returns t if the texture was loaded successfully. Otherwise nil is
1033 returned.
1035 Description
1036 The function reads an image from the file specified by the parameter name and uploads the image to
1037 OpenGL™ texture memory (using the glTexImage2D function).
1038 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1039 generated and uploaded to texture memory.
1040 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1041 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1042 corner.
1043 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1044 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1046 Notes
1047 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1048 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1049 alpha.
1050 Paletted images are translated into true color or true color + alpha pixel formats.
1051 The read texture is always rescaled to the nearest larger 2m × 2n resolution using bilinear interpolation,
1052 if necessary, since OpenGL™ requires textures to have a 2m × 2n resolution.
1053 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1054 the OpenGL™ implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1055 generated by GLFW in software.
1056 Since OpenGL™ 1.0 does not support single component alpha maps, alpha map textures are converted
1057 to RGBA format under OpenGL™ 1.0 when the +ALPHA_MAP_BIT+ flag is set and the loaded
1058 texture is a single component texture. The red, green and blue components are set to 1.0.
1063 "Parameters
1064 data
1065 The memory buffer holding the contents of the file that should be loaded.
1066 size
1067 The size, in bytes, of the memory buffer.
1068 flags
1069 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1070 Return values
1071 The function returns t if the texture was loaded successfully. Otherwise nil is
1072 returned.
1074 Description
1075 The function reads an image from the memory buffer specified by the parameter data and uploads the
1076 image to OpenGL™ texture memory (using the glTexImage2D function).
1077 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1078 generated and uploaded to texture memory.
1079 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1080 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1081 corner.
1082 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1083 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1085 Notes
1086 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1087 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1088 + alpha.
1089 Paletted images are translated into true color or true color + alpha pixel formats.
1090 The read texture is always rescaled to the nearest larger 2m × 2n resolution using bilinear interpolation,
1091 if necessary, since OpenGL™ requires textures to have a 2m × 2n resolution.
1092 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1093 the OpenGL™ implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1094 generated by GLFW in software.
1095 Since OpenGL™ 1.0 does not support single component alpha maps, alpha map textures are converted
1096 to RGBA format under OpenGL™ 1.0 when the +ALPHA_MAP_BIT+ flag is set and the loaded
1097 texture is a single component texture. The red, green and blue components are set to 1.0.
1103 "Parameters
1104 img
1105 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1106 flags
1107 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1108 Return values
1109 The function returns t if the texture was loaded successfully. Otherwise nil is
1110 returned.
1112 Description
1113 The function uploads the image specified by the parameter img to OpenGL™ texture memory (using
1114 the glTexImage2D function).
1115 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1116 generated and uploaded to texture memory.
1117 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1118 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1119 corner.
1120 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1121 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1123 Notes
1124 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1125 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1126 + alpha.
1127 Paletted images are translated into true color or true color + alpha pixel formats.
1128 The read texture is always rescaled to the nearest larger 2m × 2n resolution using bilinear interpolation,
1129 if necessary, since OpenGL™ requires textures to have a 2m × 2n resolution.
1130 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1131 the OpenGL™ implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1132 generated by GLFW in software.
1133 Since OpenGL™ 1.0 does not support single component alpha maps, alpha map textures are converted
1134 to RGBA format under OpenGL™ 1.0 when the +ALPHA_MAP_BIT+ flag is set and the loaded
1139 "Parameters
1140 extension
1141 A null terminated ISO 8859-1 string containing the name of an OpenGL™ extension.
1142 Return values
1143 The function returns t if the extension is supported. Otherwise it returns nil.
1144 Description
1145 The function does a string search in the list of supported OpenGL™ extensions to find if the specified
1146 extension is listed.
1147 Notes
1148 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1149 must have been opened with glfw::OpenWindow).
1150 In addition to checking for OpenGL™ extensions, GLFW also checks for extensions in the operating
1151 system “glue API”, such as WGL extensions under Windows and glX extensions under the X Window
1152 System.
1156 "Parameters
1157 procname
1158 A null terminated ISO 8859-1 string containing the name of an OpenGL™ extension function.
1159 Return values
1160 The function returns the pointer to the specified OpenGL™ function if it is supported, otherwise
1161 NULL is returned.
1162 Description
1163 The function acquires the pointer to an OpenGL™ extension function. Some (but not all) OpenGL™
1164 extensions define new API functions, which are usually not available through normal linking. It is
1165 therefore necessary to get access to those API functions at runtime.
1166 Notes
1167 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1168 must have been opened with glfw::OpenWindow).
1169 Some systems do not support dynamic function pointer retrieval, in which case glfw::GetProcAddress
1170 will always return NULL.
1176 "Return values
1177 The function returns the major and minor version numbers and the revision for the currently used
1178 OpenGL™ implementation as a list (major minor rev).
1180 Description
1181 The function returns the OpenGL™ implementation version. This is a convenient function that parses
1182 the version number information from the string returned by calling
1183 glGetString( GL_VERSION ). The OpenGL™ version information can be used to determine
1184 what functionality is supported by the used OpenGL™ implementation.
1186 Notes
1187 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1196 "Parameters
1197 fun
1198 A pointer to a function that acts as the entry point for the new thread. The function should have
1199 the following C language prototype:
1200 void GLFWCALL functionname( void *arg );
1201 Where functionname is the name of the thread function, and arg is the user supplied argument
1202 (see below).
1203 arg
1204 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1205 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1206 Return values
1207 The function returns a thread identification number if the thread was created successfully. This number
1208 is always positive. If the function fails, a negative number is returned.
1209 Description
1210 The function creates a new thread, which executes within the same address space as the calling process.
1211 The thread entry point is specified with the fun argument.
1212 Once the thread function fun returns, the thread dies.
1213 Notes
1214 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1215 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1218 "Parameters
1219 ID
1220 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1221 Description
1222 The function kills a running thread and removes it from the thread list.
1223 Notes
1224 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1225 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1226 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1229 "Parameters
1230 ID
1231 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1232 waitmode
1233 Can be either +WAIT+ or +NOWAIT+
1234 Return values
1235 The function returns t if the specified thread died after the function was called, or the thread
1236 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1237 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1238 running.
1241 "Return values
1242 The function returns a thread identification handle for the calling thread.
1243 Description
1244 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1245 by glfw::CreateThread when the thread was created.
1249 "Return values
1250 The function returns a mutex handle, or NULL if the mutex could not be created.
1251 Description
1252 The function creates a mutex object, which can be used to control access to data that is shared between
1253 threads.
1256 "Parameters
1257 mutex
1258 A mutex object handle.
1259 Description
1260 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1261 used by any thread.
1264 "Parameters
1265 mutex
1266 A mutex object handle.
1267 Description
1268 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1269 thread, the function will block the calling thread until it is released by the locking thread. Once the
1270 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1271 glfw::UnlockMutex.
1274 "Parameters
1275 mutex
1276 A mutex object handle.
1277 Description
1278 The function releases the lock of a locked mutex object.
1282 "Parameters
1283 mutex
1284 A mutex object handle.
1285 forms
1286 Body of code to execute
1287 Description
1288 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1289 using glfw::UnlockMutex.
1290 So, forms will not execute until an exclusive lock is held.
1291 The lock is then released when the stack is unwound."
1299 "Return values
1300 The function returns a condition variable handle, or NULL if the condition variable could not be
1301 created.
1302 Description
1303 The function creates a condition variable object, which can be used to synchronize threads.
1306 "Parameters
1307 cond
1308 A condition variable object handle.
1309 Description
1310 The function destroys a condition variable object. After a condition variable object has been destroyed,
1311 it may no longer be used by any thread.
1314 " arameters
1315 cond
1316 A condition variable object handle.
1317 mutex
1318 A mutex object handle.
1319 timeout
1320 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1321 seconds), or +INFINITY+
1322 Description
1323 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1324 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1325 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1326 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1327 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1328 Notes
1329 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1330 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1331 prepares to wait on a condition variable and another thread signals the condition just before the first
1332 thread actually waits on it.
1335 "Parameters
1336 cond
1337 A condition variable object handle.
1338 Description
1339 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1340 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1341 is not specified which.
1342 Notes
1343 When several threads are waiting for the condition variable, which thread is started depends on
1344 operating system scheduling rules, and may vary from system to system and from time to time.
1347 "Parameters
1348 cond
1349 A condition variable object handle.
1350 Description
1351 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1352 waiting on cond, nothing happens.
1353 Notes
1354 When several threads are waiting for the condition variable, the order in which threads are started
1355 depends on operating system scheduling rules, and may vary from system to system and from time to
1356 time.
1360 "Return values
1361 The function returns the number of active processors in the system.
1362 Description
1363 The function determines the number of active processors in the system.
1364 Notes
1365 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1366 Threading) processors, will report the number of logical processors.
1369 "Parameters
1370 token
1371 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1372 Return values
1373 none
1374 Description
1375 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1376 description of each feature.
1377 +AUTO_POLL_EVENTS+
1378 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1379 that glfw::SwapBuffers is called.
1380 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1381 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1382 function, since calling glfw::PollEvents from a callback function is not allowed.
1383 +KEY_REPEAT+
1384 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1385 when a key is held down long enough (according to the system key repeat configuration).
1386 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1387 when a key is pressed (and once when it is released).
1388 +MOUSE_CURSOR+
1389 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1390 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1391 the client area of the window.
1392 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1393 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1394 from the mouse, without being restricted or manipulated by the windowing system.
1395 +STICKY_KEYS+
1396 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1397 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1398 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1399 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1400 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1401 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1402 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1403 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1404 all keys.
1405 +STICKY_MOUSE_BUTTONS+
1406 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1407 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1408 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1409 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1410 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1411 glfw::GetMouseButton will never be released. Note also that enabling
1412 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1413 functionality.
1414 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1415 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1416 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1417 +SYSTEM_KEYS+
1418 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1419 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1420 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1421 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1422 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1423 the GLFW video mode again.
1424 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1425 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1426 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1429 "Parameters
1430 token
1431 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1432 Return values
1433 none
1434 Description
1435 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1436 description of each feature.
1437 +AUTO_POLL_EVENTS+
1438 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1439 that glfw::SwapBuffers is called.
1440 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1441 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1442 function, since calling glfw::PollEvents from a callback function is not allowed.
1443 +KEY_REPEAT+
1444 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1445 when a key is held down long enough (according to the system key repeat configuration).
1446 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1447 when a key is pressed (and once when it is released).
1448 +MOUSE_CURSOR+
1449 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1450 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1451 the client area of the window.
1452 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1453 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1454 from the mouse, without being restricted or manipulated by the windowing system.
1455 +STICKY_KEYS+
1456 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1457 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1458 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1459 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1460 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1461 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1462 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1463 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1464 all keys.
1465 +STICKY_MOUSE_BUTTONS+
1466 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1467 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1468 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1469 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1470 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1471 glfw::GetMouseButton will never be released. Note also that enabling
1472 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1473 functionality.
1474 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1475 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1476 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1477 +SYSTEM_KEYS+
1478 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1479 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1480 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1481 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1482 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1483 the GLFW video mode again.
1484 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1485 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1486 the GLFW program must not be interrupted (normally for games in fullscreen mode).