| blob | 45e2f0e1de6954798618904a0d183214ff4b2f1a |
15 args)))
18 args))))
25 args))
27 ,docstring
32 out-args)))))))
35 ;; ECL's DFFI seems to have issues if you don't put the full path in
48 ;; Key and button state/action definitions
52 ;; Keyboard key definitions: 8-bit ISO-8859-1 (Latin 1) encoding is used
53 ;; for printable keys (such as A-Z, 0-9 etc), and values above 256
54 ;; represent special (non-printable) keys (e.g. F1, Page Up etc).
122 ;; Mouse button definitions
133 ;; Mouse button aliases
138 ;; Joystick identifiers
158 ;;========================================================================
159 ;; Other definitions
160 ;;========================================================================
162 ;; glfwOpenWindow modes
166 ;; glfwGetWindowParam tokens
178 ;; The following constants are used for both glfwGetWindowParam
179 ;; and glfwOpenWindowHint
190 ;; glfwEnable/glfwDisable tokens
198 ;; glfwWaitThread wait modes
202 ;; glfwGetJoystickParam tokens
207 ;; glfwReadImage/glfwLoadTexture2D flags
213 ;; Time spans longer than this (seconds) are considered to be infinity
219 "Return values
220 If the function succeeds, t is returned.
221 If the function fails, nil is returned.
223 The glfwInit function initializes GLFW. No other GLFW functions may be used before this function
224 has been called.
226 Notes
227 This function may take several seconds to complete on some systems, while on other systems it may
231 "The function terminates GLFW. Among other things it closes the window, if it is opened, and kills any
237 "Return values
238 The function returns the major and minor version numbers and the revision for the currently linked
242 "Call glfw:init, execute forms and clean-up with glfw:terminate once finished.
243 This makes a nice wrapper to an application higher-level form.
244 Signals an error on failure to initialize. Wrapped in a block named glfw:with-init."
260 "width
261 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
262 not zero. If both width and height are zero, then width will be set to 640.
263 height
264 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
265 not zero. If both width and height are zero, then height will be set to 480.
266 redbits, greenbits, bluebits
267 The number of bits to use for each color component of the color buffer (0 means default color
268 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
269 buffer, if possible.
270 alphabits
271 The number of bits to use for the alpha buffer (0 means no alpha buffer).
272 depthbits
273 The number of bits to use for the depth buffer (0 means no depth buffer).
274 stencilbits
275 The number of bits to use for the stencil buffer (0 means no stencil buffer).
276 mode
277 Selects which type of OpenGL™ window to use. mode can be either GLFW_WINDOW, which
278 will generate a normal desktop window, or GLFW_FULLSCREEN, which will generate a
279 window which covers the entire screen. When GLFW_FULLSCREEN is selected, the video
280 mode will be changed to the resolution that closest matches the width and height parameters.
282 Return values
283 If the function succeeds, t is returned.
284 If the function fails, nil is returned.
286 Description
287 The function opens a window that best matches the parameters given to the function. How well the
288 resulting window matches the desired window depends mostly on the available hardware and
289 OpenGL™ drivers. In general, selecting a fullscreen mode has better chances of generating a close
290 match than does a normal desktop window, since GLFW can freely select from all the available video
291 modes. A desktop window is normally restricted to the video mode of the desktop.
293 Notes
294 For additional control of window properties, see glfwOpenWindowHint.
295 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
296 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
297 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
298 GLFW_MOUSE-CURSOR.
299 In order to determine the actual properties of an opened window, use glfwGetWindowParam and
300 glfwGetWindowSize (or glfwSetWindowSizeCallback).
301 "
306 "target
307 Can be any of the constants in the table 3.1.
308 hint
309 An integer giving the value of the corresponding target (see table 3.1).
311 Description
312 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
313 function must be called before calling glfwOpenWindow. When the glfwOpenWindow function is
314 called, any hints that were registered with the glfwOpenWindowHint function are used for setting the
315 corresponding window properties, and then all hints are reset to their default values.
317 Notes
318 In order to determine the actual properties of an opened window, use glfwGetWindowParam (after the
319 window has been opened).
320 GLFW_STEREO is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
321 pixel formats / visuals are available, glfwOpenWindow will fail.
322 The GLFW_REFRESH-RATE property should be used with caution. Most systems have default values
323 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
324 override these settings, which can result in suboptimal operation. The monitor may be unable to display
325 the resulting video signal, or in the worst case it may even be damaged!
335 "Wraps forms such that there is an open window for them to execute in and cleans up the
336 window afterwards. An error is signalled if there was an error opening the window.
337 Takes the same parameters as open-window, with the addition of 'title' which will
338 set the window title after opening.
339 Wrapped in a block named glfw:with-open-window."
340 `(if (%open-window ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
353 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
355 (with-open-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
363 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
364 setting the title given,
365 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
366 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
367 If the window is closed, the loop is also exited."
368 `(with-init-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
369 ,@setup-forms
371 ,@forms
377 "Parameters
378 cbfun
379 Pointer to a callback function that will be called when a user requests that the window should be
380 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
381 window under Microsoft Windows). The function should have the following C language
382 prototype:
383 int GLFWCALL functionname( void );
384 Where functionname is the name of the callback function. The return value of the callback
385 function indicates wether or not the window close action should continue. If the function returns
386 GL_TRUE, the window will be closed. If the function returns GL_FALSE, the window will not
387 be closed.
388 If cbfun is NULL, any previously selected callback function will be deselected.
390 If you declare your callback as returning glfw:boolean, you can use t and nil as return types.
392 Description
393 The function selects which function to be called upon a window close event.
394 A window has to be opened for this function to have any effect.
396 Notes
397 Window close events are recorded continuously, but only reported when glfwPollEvents,
398 glfwWaitEvents or glfwSwapBuffers is called.
399 The OpenGL™ context is still valid when this function is called.
400 Note that the window close callback function is not called when glfwCloseWindow is called, but only
401 when the close request comes from the window manager.
402 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
403 GL_TRUE from the function.
407 "Parameters
408 title
409 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
411 Description
412 The function changes the title of the opened window.
414 Notes
415 The title property of a window is often used in situations other than for the window title, such as the title
419 "Parameters
420 width
421 Width of the window.
422 height
423 Height of the window.
424 Return values
425 none
426 Description
427 The function changes the size of an opened window. The width and height parameters denote the size of
428 the client area of the window (i.e. excluding any window borders and decorations).
429 If the window is in fullscreen mode, the video mode will be changed to a resolution that closest matches
430 the width and height parameters (the number of color bits will not be changed).
431 Notes
432 The OpenGL™ context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
433 video mode is changed.
437 "Parameters
438 x
439 Horizontal position of the window, relative to the upper left corner of the desktop.
440 y
441 Vertical position of the window, relative to the upper left corner of the desktop.
442 Return values
443 none
444 Description
445 The function changes the position of an opened window. It does not have any effect on a fullscreen
446 window.
451 "The function is used for determining the size of an opened window. The returned values are dimensions
452 of the client area of the window (i.e. excluding any window borders and decorations).
453 (list width height)"
461 "Parameters
462 cbfun
463 Pointer to a callback function that will be called every time the window size changes. The
464 function should have the following C language prototype:
465 void GLFWCALL functionname( int width, int height );
466 Where functionname is the name of the callback function, and width and height are the
467 dimensions of the window client area.
468 If cbfun is NULL, any previously selected callback function will be deselected.
469 Return values
470 none
471 Description
472 The function selects which function to be called upon a window size change event.
473 A window has to be opened for this function to have any effect.
474 Notes
475 Window size changes are recorded continuously, but only reported when glfwPollEvents,
479 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
482 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
486 "Parameters
487 param
488 A token selecting which parameter the function should return (see table 3.2).
490 Return values
491 The function returns different parameters depending on the value of param. Table 3.2 lists valid param
492 values, and their corresponding return values.
494 Description
495 The function is used for acquiring various properties of an opened window.
497 Notes
498 GLFW_ACCELERATED is only supported under Windows. Other systems will always return
499 GL_TRUE. Under Windows, GLFW_ACCELERATED means that the OpenGL™ renderer is a 3rd
500 party renderer, rather than the fallback Microsoft software OpenGL™ renderer. In other words, it is
501 not a real guarantee that the OpenGL™ renderer is actually hardware accelerated.
505 "The function swaps the back and front color buffers of the window. If GLFW_AUTO-POLL-EVENTS
506 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
510 "Parameters
511 interval
512 Minimum number of monitor vertical retraces between each buffer swap performed by
513 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
514 refresh of the monitor (also known as ’VSync off’).
516 Description
517 The function selects the minimum number of monitor vertical retraces that should occur between two
518 buffer swaps. If the selected swap interval is one, the rate of buffer swaps will never be higher than the
519 vertical refresh rate of the monitor. If the selected swap interval is zero, the rate of buffer swaps is only
520 limited by the speed of the software and the hardware.
522 Notes
523 This function will only have an effect on hardware and drivers that support user selection of the swap
527 (defcfun+doc ("glfwSetWindowRefreshCallback" set-window-refresh-callback) :void ((cbfun :pointer))
528 "Parameters
529 cbfun
530 Pointer to a callback function that will be called when the window client area needs to be
531 refreshed. The function should have the following C language prototype:
532 void GLFWCALL functionname( void );
533 Where functionname is the name of the callback function.
534 If cbfun is NULL, any previously selected callback function will be deselected.
536 Description
537 The function selects which function to be called upon a window refresh event, which occurs when any
538 part of the window client area has been damaged, and needs to be repainted (for instance, if a part of the
539 window that was previously occluded by another window has become visible).
540 A window has to be opened for this function to have any effect.
542 Notes
543 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
544 glfwWaitEvents or glfwSwapBuffers is called.
557 "Parameters
558 maxcount
559 Maximum number of video modes that list vector can hold.
561 Return values
562 The function returns the number of detected video modes (this number will never exceed maxcount).
563 The list vector is filled out with the video modes that are supported by the system.
565 Description
566 The function returns a list of supported video modes. Each video mode is represented by a
567 list of the form:
568 (width height redbits greenbits bluebits)
570 Notes
571 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
572 resolution (Width × Height), with the lowest resolution, fewest bits per pixel mode first. "
577 collecting
587 "Parameters
588 mode
589 Pointer to a GLFWvidmode structure, which will be filled out by the function.
590 Return values
591 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
592 Description
593 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
594 for a definition of the GLFWvidmode structure.
595 Notes
596 The color depth of the desktop display is always reported as the number of bits for each individual color
597 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
598 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
599 adds up to 8 bits in total.
600 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
601 differ from the desktop video mode if the GLFW window is a fullscreen window).
602 "
612 "Description
613 The function is used for polling for events, such as user input and window resize events. Upon calling
614 this function, all window states, keyboard states and mouse states are updated. If any related callback
615 functions are registered, these are called during the call to glfwPollEvents.
617 Notes
618 glfwPollEvents is called implicitly from glfwSwapBuffers if GLFW_AUTO_POLL_EVENTS is
619 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
620 no need to call glfwPollEvents.
624 "Description
625 The function is used for waiting for events, such as user input and window resize events. Upon calling
626 this function, the calling thread will be put to sleep until any event appears in the event queue. When
627 events are ready, the events will be processed just as they are processed by glfwPollEvents.
628 If there are any events in the queue when the function is called, the function will behave exactly like
629 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
631 Notes
632 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
633 glfwPollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
634 by glfwPollEvents too, and the function may behave differently on different systems. Do no make any
635 assumptions about when or why glfwWaitEvents will return.
639 "Parameters
640 key
641 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
642 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
643 identifiers.
644 Return values
645 The function returns GLFW_PRESS if the key is held down, or GLFW_RELEASE if the key is not
646 held down.
648 Description
649 The function queries the current state of a specific keyboard key. The physical location of each key
650 depends on the system keyboard layout setting.
652 Notes
653 The constant GLFW_KEY_SPACE is equal to 32, which is the ISO 8859-1 code for space.
654 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
655 layouts, they may not be available on other keyboard layouts.
656 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
657 control), the left version is used (e.g. GLFW_KEY_LSHIFT).
658 A window must be opened for the function to have any effect, and glfwPollEvents, glfwWaitEvents or
659 glfwSwapBuffers must be called before any keyboard events are recorded and reported by
660 glfwGetKey.
664 "Parameters
665 button
666 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
667 Return values
668 The function returns GLFW_PRESS if the mouse button is held down, or GLFW_RELEASE if the
669 mouse button is not held down.
670 Description
671 The function queries the current state of a specific mouse button.
672 Notes
673 A window must be opened for the function to have any effect, and glfwPollEvents, glfwWaitEvents or
674 glfwSwapBuffers must be called before any mouse button events are recorded and reported by
675 glfwGetMouseButton.
676 GLFW_MOUSE_BUTTON_LEFT is equal to GLFW_MOUSE_BUTTON_1.
677 GLFW_MOUSE_BUTTON_RIGHT is equal to GLFW_MOUSE_BUTTON_2.
678 GLFW_MOUSE_BUTTON_MIDDLE is equal to GLFW_MOUSE_BUTTON_3.
683 "Return values
684 The function returns the current mouse position in xpos and ypos.
686 Description
687 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
688 cursor position, relative to the upper left corner of the window and limited to the client area of the
689 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
690 boundaries except to those implied by the maximum number that can be represented by a signed integer
691 (normally -2147483648 to +2147483647).
693 Notes
694 A window must be opened for the function to have any effect, and glfwPollEvents, glfwWaitEvents or
695 glfwSwapBuffers must be called before any mouse movements are recorded and reported by
696 glfwGetMousePos.
701 "Parameters
702 xpos
703 Horizontal position of the mouse.
704 ypos
705 Vertical position of the mouse.
707 Description
708 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
709 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
710 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
714 "Return values
715 The function returns the current mouse wheel position.
716 Description
717 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
718 mouse axis, which is available as a separate wheel or up/down stick on some mice.
719 Notes
720 A window must be opened for the function to have any effect, and glfwPollEvents, glfwWaitEvents or
721 glfwSwapBuffers must be called before any mouse wheel movements are recorded and reported by
722 glfwGetMouseWheel.
726 "Parameters
727 pos
728 Position of the mouse wheel.
729 Description
730 The function changes the position of the mouse wheel.
735 "Parameters
736 cbfun
737 Pointer to a callback function that will be called every time a key is pressed or released. The
738 function should have the following C language prototype:
739 void GLFWCALL functionname( int key, int action );
740 Where functionname is the name of the callback function, key is a key identifier, which is an
741 uppercase printable ISO 8859-1 character or a special key identifier (see table 3.3), and action is
742 either GLFW_PRESS or GLFW_RELEASE.
743 If cbfun is NULL, any previously selected callback function will be deselected.
744 Return values
745 none
746 Description
747 The function selects which function to be called upon a keyboard key event. The callback function is
748 called every time the state of a single key is changed (from released to pressed or vice versa). The
749 reported keys are unaffected by any modifiers (such as shift or alt).
750 A window has to be opened for this function to have any effect.
751 Notes
752 Keyboard events are recorded continuously, but only reported when glfwPollEvents, glfwWaitEvents
753 or glfwSwapBuffers is called.
756 "Parameters
757 cbfun
758 Pointer to a callback function that will be called every time a printable character is generated by
759 the keyboard. The function should have the following C language prototype:
760 void GLFWCALL functionname( int character, int action );
761 Where functionname is the name of the callback function, character is a Unicode (ISO 10646)
762 character, and action is either GLFW_PRESS or GLFW_RELEASE.
763 If cbfun is NULL, any previously selected callback function will be deselected.
764 Return values
765 none
766 Description
767 The function selects which function to be called upon a keyboard character event. The callback function
768 is called every time a key that results in a printable Unicode character is pressed or released. Characters
769 are affected by modifiers (such as shift or alt).
770 A window has to be opened for this function to have any effect.
771 Notes
772 Character events are recorded continuously, but only reported when glfwPollEvents, glfwWaitEvents
773 or glfwSwapBuffers is called.
774 Control characters, such as tab and carriage return, are not reported to the character callback function,
775 since they are not part of the Unicode character set. Use the key callback function for such events (see
776 glfwSetKeyCallback).
777 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
778 eight bit data type (e.g. the C language ’char’ type) without first checking that the character code is less
779 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
782 "Parameters
783 cbfun
784 Pointer to a callback function that will be called every time a mouse button is pressed or released.
785 The function should have the following C language prototype:
786 void GLFWCALL functionname( int button, int action );
787 Where functionname is the name of the callback function, button is a mouse button identifier (see
788 table 3.4 on page 56), and action is either GLFW_PRESS or GLFW_RELEASE.
789 If cbfun is NULL, any previously selected callback function will be deselected.
790 Return values
791 none
792 Description
793 The function selects which function to be called upon a mouse button event.
794 A window has to be opened for this function to have any effect.
795 Notes
796 Mouse button events are recorded continuously, but only reported when glfwPollEvents,
797 glfwWaitEvents or glfwSwapBuffers is called.
798 GLFW_MOUSE_BUTTON_LEFT is equal to GLFW_MOUSE_BUTTON_1.
799 GLFW_MOUSE_BUTTON_RIGHT is equal to GLFW_MOUSE_BUTTON_2.
800 GLFW_MOUSE_BUTTON_MIDDLE is equal to GLFW_MOUSE_BUTTON_3.
803 "Parameters
804 cbfun
805 Pointer to a callback function that will be called every time the mouse is moved. The function
806 should have the following C language prototype:
807 void GLFWCALL functionname( int x, int y );
808 Where functionname is the name of the callback function, and x and y are the mouse coordinates
809 (see glfwGetMousePos for more information on mouse coordinates).
810 If cbfun is NULL, any previously selected callback function will be deselected.
811 Return values
812 none
813 Description
814 The function selects which function to be called upon a mouse motion event.
815 A window has to be opened for this function to have any effect.
816 Notes
817 Mouse motion events are recorded continuously, but only reported when glfwPollEvents,
818 glfwWaitEvents or glfwSwapBuffers is called.
821 "Parameters
822 cbfun
823 Pointer to a callback function that will be called every time the mouse wheel is moved. The
824 function should have the following C language prototype:
825 void GLFWCALL functionname( int pos );
826 Where functionname is the name of the callback function, and pos is the mouse wheel position.
827 If cbfun is NULL, any previously selected callback function will be deselected.
828 Return values
829 none
830 Description
831 The function selects which function to be called upon a mouse wheel event.
832 A window has to be opened for this function to have any effect.
833 Notes
834 Mouse wheel events are recorded continuously, but only reported when glfwPollEvents,
835 glfwWaitEvents or glfwSwapBuffers is called.
839 "Parameters
840 joy
841 A joystick identifier, which should be GLFW_JOYSTICK_n, where n is in the range 1 to 16.
842 param
843 A token selecting which parameter the function should return (see table 3.5).
844 Return values
845 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
846 values, and their corresponding return values.
847 Description
848 The function is used for acquiring various properties of a joystick.
849 Notes
850 The joystick information is updated every time the function is called.
851 No window has to be opened for joystick information to be valid.
854 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
857 "Parameters
858 joy
859 A joystick identifier, which should be GLFW_JOYSTICK_n, where n is in the range 1 to 16.
860 numaxes
861 Specifies how many axes should be returned.
862 Return values
863 An list that will hold the positional values for all requested axes.
864 If the joystick is not supported or connected, the function will
865 return nil.
867 Description
868 The function queries the current position of one or more axes of a joystick. The positional values are
869 returned in an array, where the first element represents the first axis of the joystick (normally the X
870 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
871 right, forward or up, and the negative direction is left, back or down.
872 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
873 unused elements in the pos array will be set to 0.0 (zero).
875 Notes
876 The joystick state is updated every time the function is called, so there is no need to call glfwPollEvents
877 or glfwWaitEvents for joystick state to be updated.
878 Use glfwGetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
879 supported axes.
880 No window has to be opened for joystick input to be valid.
881 "
887 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
889 "Parameters
890 joy
891 A joystick identifier, which should be GLFW_JOYSTICK_n, where n is in the range 1 to 16.
892 numbuttons
893 Specifies how many buttons should be returned.
894 Return values
895 A list that will hold the button states for all requested buttons.
896 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
897 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
898 function will return 0 (zero).
900 Description
901 The function queries the current state of one or more buttons of a joystick. The button states are
902 returned in an array, where the first element represents the first button of the joystick. Each state can be
903 either GLFW_PRESS or GLFW_RELEASE.
904 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
905 available, the unused elements in the buttons array will be set to GLFW_RELEASE.
907 Notes
908 The joystick state is updated every time the function is called, so there is no need to call glfwPollEvents
909 or glfwWaitEvents for joystick state to be updated.
910 Use glfwGetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
911 supported buttons.
912 No window has to be opened for joystick input to be valid.
913 "
920 "Return values
921 The function returns the value of the high precision timer. The time is measured in seconds, and is
922 returned as a double precision floating point value.
924 Description
925 The function returns the state of a high precision timer. Unless the timer has been set by the
926 glfwSetTime function, the time is measured as the number of seconds that have passed since glfwInit
927 was called.
929 Notes
930 The resolution of the timer depends on which system the program is running on. The worst case
931 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
932 than 1 μs.
936 "Parameters
937 time
938 Time (in seconds) that the timer should be set to.
940 Description
941 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
942 glfwGetTime will be relative to this time. The time is given in seconds.
946 "Parameters
947 time
948 Time, in seconds, to sleep.
950 Description
951 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
952 put to sleep. Other threads within the same process can still execute.
954 Notes
955 There is usually a system dependent minimum time for which it is possible to sleep. This time is
956 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
957 shorter time as a parameter to glfwSleep can give one of two results: either the thread will sleep for the
958 minimum possible sleep time, or the thread will not sleep at all (glfwSleep returns immediately). The
970 "Parameters
971 name
972 A null terminated ISO 8859-1 string holding the name of the file that should be read.
973 img
974 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
975 read was successful).
976 flags
977 Flags for controlling the image reading process. Valid flags are listed in table 3.6
978 Return values
979 The function returns t if the image was loaded successfully. Otherwise nil is
980 returned.
981 Description
982 The function reads an image from the file specified by the parameter name and returns the image
983 information and data in a GLFWimage structure, which has the following definition:
984 § ¤
985 typedef struct {
986 int Width, Height; // Image dimensions
987 int Format; // OpenGL pixel format
988 int BytesPerPixel; // Number of bytes per pixel
989 unsigned char *Data; // Pointer to pixel data
990 } GLFWimage;
991 ¦ ¥
992 Width and Height give the dimensions of the image. Format specifies an OpenGL™ pixel format,
993 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
994 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
995 By default the read image is rescaled to the nearest larger 2m × 2n resolution using bilinear
996 interpolation, if necessary, which is useful if the image is to be used as an OpenGL™ texture. This
997 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
998 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
999 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1000 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1001 GLFW_ALPHA_MAP_BIT flag is set, otherwise Format is set to GL_LUMINANCE.
1002 Notes
1003 glfwReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
1004 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
1005 Paletted images are translated into true color or true color + alpha pixel formats.
1006 Please note that OpenGL™ 1.0 does not support single component alpha maps, so do not use images
1007 with Format = GL_ALPHA directly as textures under OpenGL™ 1.0.
1012 "Parameters
1013 data
1014 The memory buffer holding the contents of the file that should be read.
1015 size
1016 The size, in bytes, of the memory buffer.
1017 img
1018 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1019 read was successful).
1020 flags
1021 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1022 Return values
1023 The function returns t if the image was loaded successfully. Otherwise nil is
1024 returned.
1025 Description
1026 The function reads an image from the memory buffer specified by the parameter data and returns the
1027 image information and data in a GLFWimage structure, which has the following definition:
1028 § ¤
1029 typedef struct {
1030 int Width, Height; // Image dimensions
1031 int Format; // OpenGL pixel format
1032 int BytesPerPixel; // Number of bytes per pixel
1033 unsigned char *Data; // Pointer to pixel data
1034 } GLFWimage;
1035 ¦ ¥
1036 Width and Height give the dimensions of the image. Format specifies an OpenGL™ pixel format,
1037 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1038 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1039 By default the read image is rescaled to the nearest larger 2m × 2n resolution using bilinear
1040 interpolation, if necessary, which is useful if the image is to be used as an OpenGL™ texture. This
1041 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1042 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1043 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1044 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1045 GLFW_ALPHA_MAP_BIT flag is set, otherwise Format is set to GL_LUMINANCE.
1046 Notes
1047 glfwReadMemoryImage 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 Please note that OpenGL™ 1.0 does not support single component alpha maps, so do not use images
1052 with Format = GL_ALPHA directly as textures under OpenGL™ 1.0.
1056 "Parameters
1057 img
1058 Pointer to a GLFWimage struct.
1059 Description
1060 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1061 struct. Any image that has been loaded by the glfwReadImage function should be deallocated using
1065 "Parameters
1066 name
1067 An ISO 8859-1 string holding the name of the file that should be loaded.
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 file specified by the parameter name and uploads the image to
1076 OpenGL™ texture memory (using the glTexImage2D function).
1077 If the GLFW_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 GLFW_ORIGIN_UL_BIT is set, the origin of the texture is the lower left corner of the
1080 loaded image. If the flag GLFW_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 GLFW_ALPHA_MAP_BIT flag is set, otherwise it is uploaded as a luminance texture.
1085 Notes
1086 glfwLoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1087 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 GLFW_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.
1102 "Parameters
1103 data
1104 The memory buffer holding the contents of the file that should be loaded.
1105 size
1106 The size, in bytes, of the memory buffer.
1107 flags
1108 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1109 Return values
1110 The function returns t if the texture was loaded successfully. Otherwise nil is
1111 returned.
1113 Description
1114 The function reads an image from the memory buffer specified by the parameter data and uploads the
1115 image to OpenGL™ texture memory (using the glTexImage2D function).
1116 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1117 generated and uploaded to texture memory.
1118 Unless the flag GLFW_ORIGIN_UL_BIT is set, the origin of the texture is the lower left corner of the
1119 loaded image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left
1120 corner.
1121 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1122 GLFW_ALPHA_MAP_BIT flag is set, otherwise it is uploaded as a luminance texture.
1124 Notes
1125 glfwLoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1126 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1127 + alpha.
1128 Paletted images are translated into true color or true color + alpha pixel formats.
1129 The read texture is always rescaled to the nearest larger 2m × 2n resolution using bilinear interpolation,
1130 if necessary, since OpenGL™ requires textures to have a 2m × 2n resolution.
1131 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1132 the OpenGL™ implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1133 generated by GLFW in software.
1134 Since OpenGL™ 1.0 does not support single component alpha maps, alpha map textures are converted
1135 to RGBA format under OpenGL™ 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1136 texture is a single component texture. The red, green and blue components are set to 1.0.
1142 "Parameters
1143 img
1144 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1145 flags
1146 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1147 Return values
1148 The function returns t if the texture was loaded successfully. Otherwise nil is
1149 returned.
1151 Description
1152 The function uploads the image specified by the parameter img to OpenGL™ texture memory (using
1153 the glTexImage2D function).
1154 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1155 generated and uploaded to texture memory.
1156 Unless the flag GLFW_ORIGIN_UL_BIT is set, the origin of the texture is the lower left corner of the
1157 loaded image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left
1158 corner.
1159 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1160 GLFW_ALPHA_MAP_BIT flag is set, otherwise it is uploaded as a luminance texture.
1162 Notes
1163 glfwLoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1164 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1165 + alpha.
1166 Paletted images are translated into true color or true color + alpha pixel formats.
1167 The read texture is always rescaled to the nearest larger 2m × 2n resolution using bilinear interpolation,
1168 if necessary, since OpenGL™ requires textures to have a 2m × 2n resolution.
1169 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1170 the OpenGL™ implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1171 generated by GLFW in software.
1172 Since OpenGL™ 1.0 does not support single component alpha maps, alpha map textures are converted
1173 to RGBA format under OpenGL™ 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1178 "Parameters
1179 extension
1180 A null terminated ISO 8859-1 string containing the name of an OpenGL™ extension.
1181 Return values
1182 The function returns t if the extension is supported. Otherwise it returns nil.
1183 Description
1184 The function does a string search in the list of supported OpenGL™ extensions to find if the specified
1185 extension is listed.
1186 Notes
1187 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1188 must have been opened with glfwOpenWindow).
1189 In addition to checking for OpenGL™ extensions, GLFW also checks for extensions in the operating
1190 system “glue API”, such as WGL extensions under Windows and glX extensions under the X Window
1191 System.
1195 "Parameters
1196 procname
1197 A null terminated ISO 8859-1 string containing the name of an OpenGL™ extension function.
1198 Return values
1199 The function returns the pointer to the specified OpenGL™ function if it is supported, otherwise
1200 NULL is returned.
1201 Description
1202 The function acquires the pointer to an OpenGL™ extension function. Some (but not all) OpenGL™
1203 extensions define new API functions, which are usually not available through normal linking. It is
1204 therefore necessary to get access to those API functions at runtime.
1205 Notes
1206 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1207 must have been opened with glfwOpenWindow).
1208 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1209 will always return NULL.
1215 "Return values
1216 The function returns the major and minor version numbers and the revision for the currently used
1217 OpenGL™ implementation as a list (major minor rev).
1219 Description
1220 The function returns the OpenGL™ implementation version. This is a convenient function that parses
1221 the version number information from the string returned by calling
1222 glGetString( GL_VERSION ). The OpenGL™ version information can be used to determine
1223 what functionality is supported by the used OpenGL™ implementation.
1225 Notes
1226 An OpenGL™ context must be created before this function can be called (i.e. an OpenGL™ window
1235 "Parameters
1236 fun
1237 A pointer to a function that acts as the entry point for the new thread. The function should have
1238 the following C language prototype:
1239 void GLFWCALL functionname( void *arg );
1240 Where functionname is the name of the thread function, and arg is the user supplied argument
1241 (see below).
1242 arg
1243 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1244 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1245 Return values
1246 The function returns a thread identification number if the thread was created successfully. This number
1247 is always positive. If the function fails, a negative number is returned.
1248 Description
1249 The function creates a new thread, which executes within the same address space as the calling process.
1250 The thread entry point is specified with the fun argument.
1251 Once the thread function fun returns, the thread dies.
1252 Notes
1253 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1254 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1257 "Parameters
1258 ID
1259 A thread identification handle, which is returned by glfwCreateThread or glfwGetThreadID.
1260 Description
1261 The function kills a running thread and removes it from the thread list.
1262 Notes
1263 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1264 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1265 thread communication, and use glfwWaitThread in order to wait for the thread to die.
1268 "Parameters
1269 ID
1270 A thread identification handle, which is returned by glfwCreateThread or glfwGetThreadID.
1271 waitmode
1272 Can be either GLFW_WAIT or GLFW_NOWAIT.
1273 Return values
1274 The function returns t if the specified thread died after the function was called, or the thread
1275 did not exist, in which case glfwWaitThread will return immediately regardless of waitmode. The
1276 function returns nil if waitmode is GLFW_NOWAIT, and the specified thread exists and is still
1277 running.
1280 "Return values
1281 The function returns a thread identification handle for the calling thread.
1282 Description
1283 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1284 by glfwCreateThread when the thread was created.
1288 "Return values
1289 The function returns a mutex handle, or NULL if the mutex could not be created.
1290 Description
1291 The function creates a mutex object, which can be used to control access to data that is shared between
1292 threads.
1295 "Parameters
1296 mutex
1297 A mutex object handle.
1298 Description
1299 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1300 used by any thread.
1303 "Parameters
1304 mutex
1305 A mutex object handle.
1306 Description
1307 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1308 thread, the function will block the calling thread until it is released by the locking thread. Once the
1309 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1310 glfwUnlockMutex.
1313 "Parameters
1314 mutex
1315 A mutex object handle.
1316 Description
1317 The function releases the lock of a locked mutex object.
1321 "Parameters
1322 mutex
1323 A mutex object handle.
1324 forms
1325 Body of code to execute
1326 Description
1327 This macro will acquire a lock on the selected mutex object using glfwLockMutex and release it afterwards
1328 using glfwUnlockMutex.
1329 So, forms will not execute until an exclusive lock is held.
1330 The lock is then released when the stack is unwound."
1338 "Return values
1339 The function returns a condition variable handle, or NULL if the condition variable could not be
1340 created.
1341 Description
1342 The function creates a condition variable object, which can be used to synchronize threads.
1345 "Parameters
1346 cond
1347 A condition variable object handle.
1348 Description
1349 The function destroys a condition variable object. After a condition variable object has been destroyed,
1350 it may no longer be used by any thread.
1353 " arameters
1354 cond
1355 A condition variable object handle.
1356 mutex
1357 A mutex object handle.
1358 timeout
1359 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1360 seconds), or GLFW_INFINITY.
1361 Description
1362 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1363 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1364 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1365 GLFW_INFINITY, glfwWaitCond will wait forever for cond to be signaled. Before returning to the
1366 calling thread, glfwWaitCond automatically re-acquires the mutex.
1367 Notes
1368 The mutex specified by mutex must be locked by the calling thread before entrance to glfwWaitCond.
1369 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1370 prepares to wait on a condition variable and another thread signals the condition just before the first
1371 thread actually waits on it.
1374 "Parameters
1375 cond
1376 A condition variable object handle.
1377 Description
1378 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1379 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1380 is not specified which.
1381 Notes
1382 When several threads are waiting for the condition variable, which thread is started depends on
1383 operating system scheduling rules, and may vary from system to system and from time to time.
1386 "Parameters
1387 cond
1388 A condition variable object handle.
1389 Description
1390 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1391 waiting on cond, nothing happens.
1392 Notes
1393 When several threads are waiting for the condition variable, the order in which threads are started
1394 depends on operating system scheduling rules, and may vary from system to system and from time to
1395 time.
1399 "Return values
1400 The function returns the number of active processors in the system.
1401 Description
1402 The function determines the number of active processors in the system.
1403 Notes
1404 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1405 Threading) processors, will report the number of logical processors.
1408 "Parameters
1409 token
1410 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1411 Return values
1412 none
1413 Description
1414 glfwEnable is used to enable a certain feature, while glfwDisable is used to disable it. Below follows a
1415 description of each feature.
1416 GLFW_AUTO_POLL_EVENTS
1417 When GLFW_AUTO_POLL_EVENTS is enabled, glfwPollEvents is automatically called each time
1418 that glfwSwapBuffers is called.
1419 When GLFW_AUTO_POLL_EVENTS is disabled, calling glfwSwapBuffers will not result in a call to
1420 glfwPollEvents. This can be useful if glfwSwapBuffers needs to be called from within a callback
1421 function, since calling glfwPollEvents from a callback function is not allowed.
1422 GLFW_KEY_REPEAT
1423 When GLFW_KEY_REPEAT is enabled, the key and character callback functions are called repeatedly
1424 when a key is held down long enough (according to the system key repeat configuration).
1425 When GLFW_KEY_REPEAT is disabled, the key and character callback functions are only called once
1426 when a key is pressed (and once when it is released).
1427 GLFW_MOUSE_CURSOR
1428 When GLFW_MOUSE_CURSOR is enabled, the mouse cursor is visible, and mouse coordinates are
1429 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1430 the client area of the window.
1431 When GLFW_MOUSE_CURSOR is disabled, the mouse cursor is invisible, and mouse coordinates are
1432 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1433 from the mouse, without being restricted or manipulated by the windowing system.
1434 GLFW_STICKY_KEYS
1435 When GLFW_STICKY_KEYS is enabled, keys which are pressed will not be released until they are
1436 physically released and checked with glfwGetKey. This behavior makes it possible to catch keys that
1437 were pressed and then released again between two calls to glfwPollEvents, glfwWaitEvents or
1438 glfwSwapBuffers, which would otherwise have been reported as released. Care should be taken when
1439 using this mode, since keys that are not checked with glfwGetKey will never be released. Note also that
1440 enabling GLFW_STICKY_KEYS does not affect the behavior of the keyboard callback functionality.
1441 When GLFW_STICKY_KEYS is disabled, the status of a key that is reported by glfwGetKey is always
1442 the physical state of the key. Disabling GLFW_STICKY_KEYS also clears the sticky information for
1443 all keys.
1444 GLFW_STICKY_MOUSE_BUTTONS
1445 When GLFW_STICKY_MOUSE_BUTTONS is enabled, mouse buttons that are pressed will not be
1446 released until they are physically released and checked with glfwGetMouseButton. This behavior
1447 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1448 to glfwPollEvents, glfwWaitEvents or glfwSwapBuffers, which would otherwise have been reported
1449 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1450 glfwGetMouseButton will never be released. Note also that enabling
1451 GLFW_STICKY_MOUSE_BUTTONS does not affect the behavior of the mouse button callback
1452 functionality.
1453 When GLFW_STICKY_MOUSE_BUTTONS is disabled, the status of a mouse button that is reported
1454 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1455 GLFW_STICKY_MOUSE_BUTTONS also clears the sticky information for all mouse buttons.
1456 GLFW_SYSTEM_KEYS
1457 When GLFW_SYSTEM_KEYS is enabled, pressing standard system key combinations, such as
1458 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1459 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1460 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1461 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1462 the GLFW video mode again.
1463 When GLFW_SYSTEM_KEYS is disabled, pressing standard system key combinations will have no
1464 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1465 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1468 "Parameters
1469 token
1470 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1471 Return values
1472 none
1473 Description
1474 glfwEnable is used to enable a certain feature, while glfwDisable is used to disable it. Below follows a
1475 description of each feature.
1476 GLFW_AUTO_POLL_EVENTS
1477 When GLFW_AUTO_POLL_EVENTS is enabled, glfwPollEvents is automatically called each time
1478 that glfwSwapBuffers is called.
1479 When GLFW_AUTO_POLL_EVENTS is disabled, calling glfwSwapBuffers will not result in a call to
1480 glfwPollEvents. This can be useful if glfwSwapBuffers needs to be called from within a callback
1481 function, since calling glfwPollEvents from a callback function is not allowed.
1482 GLFW_KEY_REPEAT
1483 When GLFW_KEY_REPEAT is enabled, the key and character callback functions are called repeatedly
1484 when a key is held down long enough (according to the system key repeat configuration).
1485 When GLFW_KEY_REPEAT is disabled, the key and character callback functions are only called once
1486 when a key is pressed (and once when it is released).
1487 GLFW_MOUSE_CURSOR
1488 When GLFW_MOUSE_CURSOR is enabled, the mouse cursor is visible, and mouse coordinates are
1489 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1490 the client area of the window.
1491 When GLFW_MOUSE_CURSOR is disabled, the mouse cursor is invisible, and mouse coordinates are
1492 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1493 from the mouse, without being restricted or manipulated by the windowing system.
1494 GLFW_STICKY_KEYS
1495 When GLFW_STICKY_KEYS is enabled, keys which are pressed will not be released until they are
1496 physically released and checked with glfwGetKey. This behavior makes it possible to catch keys that
1497 were pressed and then released again between two calls to glfwPollEvents, glfwWaitEvents or
1498 glfwSwapBuffers, which would otherwise have been reported as released. Care should be taken when
1499 using this mode, since keys that are not checked with glfwGetKey will never be released. Note also that
1500 enabling GLFW_STICKY_KEYS does not affect the behavior of the keyboard callback functionality.
1501 When GLFW_STICKY_KEYS is disabled, the status of a key that is reported by glfwGetKey is always
1502 the physical state of the key. Disabling GLFW_STICKY_KEYS also clears the sticky information for
1503 all keys.
1504 GLFW_STICKY_MOUSE_BUTTONS
1505 When GLFW_STICKY_MOUSE_BUTTONS is enabled, mouse buttons that are pressed will not be
1506 released until they are physically released and checked with glfwGetMouseButton. This behavior
1507 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1508 to glfwPollEvents, glfwWaitEvents or glfwSwapBuffers, which would otherwise have been reported
1509 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1510 glfwGetMouseButton will never be released. Note also that enabling
1511 GLFW_STICKY_MOUSE_BUTTONS does not affect the behavior of the mouse button callback
1512 functionality.
1513 When GLFW_STICKY_MOUSE_BUTTONS is disabled, the status of a mouse button that is reported
1514 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1515 GLFW_STICKY_MOUSE_BUTTONS also clears the sticky information for all mouse buttons.
1516 GLFW_SYSTEM_KEYS
1517 When GLFW_SYSTEM_KEYS is enabled, pressing standard system key combinations, such as
1518 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1519 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1520 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1521 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1522 the GLFW video mode again.
1523 When GLFW_SYSTEM_KEYS is disabled, pressing standard system key combinations will have no
1524 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1525 the GLFW program must not be interrupted (normally for games in fullscreen mode).