lib/glfw.lisp

   1 (in-package #:cl-glfw)
   2
   3 ;; Keyboard key definitions: 8-bit ISO-8859-1 (Latin 1) encoding is used
   4 ;; for printable keys (such as A-Z, 0-9 etc), and values above 256
   5 ;; represent special (non-printable) keys (e.g. F1, Page Up etc).
   6 (define-foreign-type key-code-type ()
   7   ()
   8   (:actual-type :int)
   9   (:simple-parser key-code))
  10
  11 (eval-when (:compile-toplevel :load-toplevel)
  12   (defmethod expand-to-foreign (value (type key-code-type))
  13     `(cl:cond ((characterp ,value) (char-code ,value))
  14               ((symbolp ,value) (ecase ,value
  15                                   (:unknown -1)
  16                                   (:space 32)
  17                                   (:esc 257)
  18                                   (:f1 258)
  19                                   (:f2 259)
  20                                   (:f3 260)
  21                                   (:f4 261)
  22                                   (:f5 262)
  23                                   (:f6 263)
  24                                   (:f7 264)
  25                                   (:f8 265)
  26                                   (:f9 266)
  27                                   (:f10 267)
  28                                   (:f11 268)
  29                                   (:f12 269)
  30                                   (:f13 270)
  31                                   (:f14 271)
  32                                   (:f15 272)
  33                                   (:f16 273)
  34                                   (:f17 274)
  35                                   (:f18 275)
  36                                   (:f19 276)
  37                                   (:f20 277)
  38                                   (:f21 278)
  39                                   (:f22 279)
  40                                   (:f23 280)
  41                                   (:f24 281)
  42                                   (:f25 282)
  43                                   (:up 283)
  44                                   (:down 284)
  45                                   (:left 285)
  46                                   (:right 286)
  47                                   (:lshift 287)
  48                                   (:rshift 288)
  49                                   (:lctrl 289)
  50                                   (:rctrl 290)
  51                                   (:lalt 291)
  52                                   (:ralt 292)
  53                                   (:tab 293)
  54                                   (:enter 294)
  55                                   (:backspace 295)
  56                                   (:insert 296)
  57                                   (:del 297)
  58                                   (:pageup 298)
  59                                   (:pagedown 299)
  60                                   (:home 300)
  61                                   (:end 301)
  62                                   (:kp-0 302)
  63                                   (:kp-1 303)
  64                                   (:kp-2 304)
  65                                   (:kp-3 305)
  66                                   (:kp-4 306)
  67                                   (:kp-5 307)
  68                                   (:kp-6 308)
  69                                   (:kp-7 309)
  70                                   (:kp-8 310)
  71                                   (:kp-9 311)
  72                                   (:kp-divide 312)
  73                                   (:kp-multiply 313)
  74                                   (:kp-subtract 314)
  75                                   (:kp-add 315)
  76                                   (:kp-decimal 316)
  77                                   (:kp-equal 317)
  78                                   (:kp-enter 318)))
  79               (t ,value))))
  80
  81 ;; Mouse button definitions
  82 (defconstant +mouse-button-1+ 0)
  83 (defconstant +mouse-button-2+ 1)
  84 (defconstant +mouse-button-3+ 2)
  85 (defconstant +mouse-button-4+ 3)
  86 (defconstant +mouse-button-5+ 4)
  87 (defconstant +mouse-button-6+ 5)
  88 (defconstant +mouse-button-7+ 6)
  89 (defconstant +mouse-button-8+ 7)
  90 (defconstant +mouse-button-last+ +mouse-button-8+)
  91
  92 ;; Mouse button aliases
  93 (defconstant +mouse-button-left+ +mouse-button-1+)
  94 (defconstant +mouse-button-right+ +mouse-button-2+)
  95 (defconstant +mouse-button-middle+ +mouse-button-3+)
  96
  97 ;; Joystick identifiers
  98 (defconstant +joystick-1+ 0)
  99 (defconstant +joystick-2+ 1)
 100 (defconstant +joystick-3+ 2)
 101 (defconstant +joystick-4+ 3)
 102 (defconstant +joystick-5+ 4)
 103 (defconstant +joystick-6+ 5)
 104 (defconstant +joystick-7+ 6)
 105 (defconstant +joystick-8+ 7)
 106 (defconstant +joystick-9+ 8)
 107 (defconstant +joystick-10+ 9)
 108 (defconstant +joystick-11+ 10)
 109 (defconstant +joystick-12+ 11)
 110 (defconstant +joystick-13+ 12)
 111 (defconstant +joystick-14+ 13)
 112 (defconstant +joystick-15+ 14)
 113 (defconstant +joystick-16+ 15)
 114 (defconstant +joystick-last+ +joystick-16+)
 115
 116
 117 ;;========================================================================
 118  ;; Other definitions
 119 ;;========================================================================
 120
 121 ;; glfwOpenWindow modes
 122 (defcenum open-window-mode
 123   (:window #x00010001)
 124   (:full-screen #x00010002))
 125
 126 ;; glfwGetWindowParam tokens
 127 (defcenum window-parameter
 128   (:opened #x00020001)
 129   (:active #x00020002)
 130   (:iconified #x00020003)
 131   (:accelerated #x00020004)
 132   (:red-bits #x00020005)
 133   (:green-bits #x00020006)
 134   (:blue-bits #x00020007)
 135   (:alpha-bits #x00020008)
 136   (:depth-bits #x00020009)
 137   (:stencil-bits #x0002000a)
 138
 139 ;; The following constants are used for both glfwGetWindowParam
 140 ;; and glfwOpenWindowHint
 141   (:refresh-rate #x0002000b)
 142   (:accum-red-bits #x0002000c)
 143   (:accum-green-bits #x0002000d)
 144   (:accum-blue-bits #x0002000e)
 145   (:accum-alpha-bits #x0002000f)
 146   (:aux-buffers #x00020010)
 147   (:stereo #x00020011)
 148   (:window-no-resize #x00020012)
 149   (:fsaa-samples #x00020013))
 150
 151 ;; glfwEnable/glfwDisable tokens
 152 (defcenum boolean-token
 153   (:mouse-cursor #x00030001)
 154   (:sticky-keys #x00030002)
 155   (:sticky-mouse-buttons #x00030003)
 156   (:system-keys #x00030004)
 157   (:key-repeat #x00030005)
 158   (:auto-poll-events #x00030006))
 159
 160 ;; glfwWaitThread wait modes
 161 (define-foreign-type wait-mode-type ()
 162   ()
 163   (:actual-type :int)
 164   (:simple-parser wait-mode))
 165
 166 (eval-when (:compile-toplevel :load-toplevel)
 167   (defmethod expand-to-foreign (value (type wait-mode-type))
 168     `(if ,value #x00040001 #x00040002)))
 169
 170 ;; glfwGetJoystickParam tokens
 171 (defcenum joystick-param-token
 172   (:present #x00050001)
 173   (:axes #x00050002)
 174   (:buttons #x00050003))
 175
 176 ;; glfwReadImage/glfwLoadTexture2D flags
 177 (defcenum image-flag
 178   (:no-rescale #x00000001) ; Only for glfwReadImage
 179   (:origin-ul #x00000002)
 180   (:build-mipmaps #x00000004) ; Only for glfwLoadTexture2D
 181   (:alpha-map #x00000008))
 182
 183 ;; Time spans longer than this (seconds) are considered to be infinity
 184 (defconstant +infinity+ 100000d0)
 185
 186 (defcfun+doc ("glfwInit" init) boolean ()
 187   "Return values
 188 If the function succeeds, t is returned.
 189 If the function fails, nil is returned.
 190
 191 The glfwInit function initializes GLFW. No other GLFW functions may be used before this function
 192 has been called.
 193
 194 Notes
 195 This function may take several seconds to complete on some systems, while on other systems it may
 196 take only a fraction of a second to complete.")
 197
 198 (defcfun+doc ("glfwTerminate" terminate) :void ()
 199       "The function terminates GLFW. Among other things it closes the window, if it is opened, and kills any
 200 running threads. This function must be called before a program exits.")
 201
 202 (defcfun+out+doc ("glfwGetVersion" get-version) :void ((:out major :int)
 203                                                        (:out minor :int)
 204                                                        (:out rev :int))
 205                  "Return values
 206 The function returns the major and minor version numbers and the revision for the currently linked
 207 GLFW library as a list (major minor rev).")
 208
 209 (defmacro with-init (&body forms)
 210   "Call glfw:init, execute forms and clean-up with glfw:terminate once finished.
 211 This makes a nice wrapper to an application higher-level form.
 212 Signals an error on failure to initialize. Wrapped in a block named glfw:with-init."
 213   `(if (glfw:init)
 214        (unwind-protect
 215             (block with-init ,@forms)
 216          (glfw:terminate))
 217        (error "Error initializing glfw.")))
 218
 219 (defcfun ("glfwOpenWindow" %open-window) boolean
 220   (width :int) (height :int)
 221   (redbits :int) (greenbits :int) (bluebits :int) (alphabits :int)
 222   (depthbits :int) (stencilbits :int) (mode open-window-mode))
 223
 224 (declaim (inline open-window))
 225 (defun open-window (&optional (width 0) (height 0)
 226                     (redbits 0) (greenbits 0) (bluebits 0) (alphabits 0)
 227                     (depthbits 0) (stencilbits 0) (mode :window))
 228   "width
 229       The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
 230       not zero. If both width and height are zero, then width will be set to 640.
 231 height
 232       The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
 233       not zero. If both width and height are zero, then height will be set to 480.
 234 redbits, greenbits, bluebits
 235       The number of bits to use for each color component of the color buffer (0 means default color
 236       depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
 237       buffer, if possible.
 238 alphabits
 239       The number of bits to use for the alpha buffer (0 means no alpha buffer).
 240 depthbits
 241       The number of bits to use for the depth buffer (0 means no depth buffer).
 242 stencilbits
 243       The number of bits to use for the stencil buffer (0 means no stencil buffer).
 244 mode
 245       Selects which type of OpenGL window to use. mode can be either :WINDOW, which
 246       will generate a normal desktop window, or :FULL-SCREEN which will generate a
 247       window which covers the entire screen. When :FULL-SCREEN is selected, the video
 248       mode will be changed to the resolution that closest matches the width and height parameters.
 249
 250 Return values
 251 If the function succeeds, t is returned.
 252 If the function fails, nil is returned.
 253
 254 Description
 255
 256 The function opens a window that best matches the parameters given to
 257 the function. How well the resulting window matches the desired window
 258 depends mostly on the available hardware and OpenGL drivers. In
 259 general, selecting a fullscreen mode has better chances of generating
 260 a close match than does a normal desktop window, since GLFW can freely
 261 select from all the available video modes. A desktop window is
 262 normally restricted to the video mode of the desktop.
 263
 264 Notes
 265
 266 For additional control of window properties, see glfw::OpenWindowHint.
 267 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
 268 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
 269 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
 270 +MOUSE_CURSOR+
 271 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
 272 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
 273 "
 274   (%open-window width height redbits greenbits bluebits alphabits depthbits stencilbits mode))
 275
 276
 277 (defcfun+doc ("glfwOpenWindowHint" open-window-hint) :void ((target window-parameter) (hint :int))
 278          "target
 279        Can be any of the constants in the table 3.1.
 280 hint
 281        An integer giving the value of the corresponding target (see table 3.1).
 282
 283 Description
 284 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
 285 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
 286 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
 287 corresponding window properties, and then all hints are reset to their default values.
 288
 289 Notes
 290 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
 291 window has been opened).
 292 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
 293 pixel formats / visuals are available, glfw::OpenWindow will fail.
 294 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
 295 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
 296 override these settings, which can result in suboptimal operation. The monitor may be unable to display
 297 the resulting video signal, or in the worst case it may even be damaged!
 298 ")
 299
 300 (defcfun+doc ("glfwCloseWindow" close-window) :void ()
 301          "The function closes an opened window and destroys the associated OpenGL context.")
 302
 303 (defmacro with-open-window ((&optional (title "cl-glfw window") (width 0) (height 0)
 304                                        (redbits 0) (greenbits 0) (bluebits 0) (alphabits 0)
 305                                        (depthbits 0) (stencilbits 0) (mode :window))
 306                             &body forms)
 307   "Wraps forms such that there is an open window for them to execute in and cleans up the
 308 window afterwards. An error is signalled if there was an error opening the window.
 309 Takes the same parameters as open-window, with the addition of 'title' which will
 310 set the window title after opening.
 311 Wrapped in a block named glfw:with-open-window."
 312   `(if (%open-window ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
 313        (unwind-protect
 314             (block with-open-window
 315               (glfw:set-window-title ,title)
 316               ,@forms)
 317          (when (glfw:get-window-param :opened)
 318            (close-window)))
 319        (error "Error initializing glfw window.")))
 320
 321 (defmacro with-init-window ((&optional (title "cl-glfw window") (width 0) (height 0)
 322                                        (redbits 0) (greenbits 0) (bluebits 0) (alphabits 0)
 323                                        (depthbits 0) (stencilbits 0) (mode :window))
 324                             &body forms)
 325   "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
 326   `(with-init
 327      (with-open-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
 328        ,@forms)))
 329
 330 (defmacro do-window ((&optional (title "cl-glfw window") (width 0) (height 0)
 331                                 (redbits 0) (greenbits 0) (bluebits 0) (alphabits 0)
 332                                 (depthbits 0) (stencilbits 0) (mode :window))
 333                      (&body setup-forms)
 334                      &body forms)
 335   "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
 336 setting the title given,
 337 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
 338 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
 339 If the window is closed, the loop is also exited."
 340   `(with-init-window (,title ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
 341      ,@setup-forms
 342      (loop named do-window do
 343           ,@forms
 344           (glfw:swap-buffers)
 345           (unless (glfw:get-window-param :opened)
 346             (return-from do-window)))))
 347
 348 (defcfun+doc ("glfwSetWindowCloseCallback" set-window-close-callback) :void ((cbfun :pointer))
 349              "Parameters
 350 cbfun
 351       Pointer to a callback function that will be called when a user requests that the window should be
 352       closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
 353       window under Microsoft Windows). The function should have the following C language
 354       prototype:
 355       int GLFWCALL functionname( void );
 356       Where functionname is the name of the callback function. The return value of the callback
 357       function indicates wether or not the window close action should continue. If the function returns
 358       GL_TRUE, the window will be closed. If the function returns GL_FALSE, the window will not
 359       be closed.
 360       If cbfun is NULL, any previously selected callback function will be deselected.
 361
 362       If you declare your callback as returning glfw:boolean, you can use t and nil as return types.
 363
 364 Description
 365 The function selects which function to be called upon a window close event.
 366 A window has to be opened for this function to have any effect.
 367
 368 Notes
 369 Window close events are recorded continuously, but only reported when glfwPollEvents,
 370 glfwWaitEvents or glfwSwapBuffers is called.
 371 The OpenGL context is still valid when this function is called.
 372 Note that the window close callback function is not called when glfwCloseWindow is called, but only
 373 when the close request comes from the window manager.
 374 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
 375 GL_TRUE from the function.
 376 ")
 377
 378 (defcfun+doc ("glfwSetWindowTitle" set-window-title) :void ((title :string))
 379              "Parameters
 380 title
 381        Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
 382
 383 Description
 384 The function changes the title of the opened window.
 385
 386 Notes
 387 The title property of a window is often used in situations other
 388 than for the window title, such as the title of an application icon
 389 when it is in iconified state.")
 390
 391 (defcfun+doc ("glfwSetWindowSize" set-window-size) :void ((width :int) (height :int))
 392              "Parameters
 393 width
 394        Width of the window.
 395 height
 396        Height of the window.
 397 Return values
 398 none
 399 Description
 400
 401 The function changes the size of an opened window. The width and
 402 height parameters denote the size of the client area of the
 403 window (i.e. excluding any window borders and decorations).  If the
 404 window is in fullscreen mode, the video mode will be changed to a
 405 resolution that closest matches the width and height parameters (the
 406 number of color bits will not be changed).
 407
 408 Notes
 409
 410 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
 411 video mode is changed.
 412 ")
 413
 414 (defcfun+doc ("glfwSetWindowPos" set-window-pos) :void ((x :int) (y :int))
 415              "Parameters
 416 x
 417       Horizontal position of the window, relative to the upper left corner of the desktop.
 418 y
 419       Vertical position of the window, relative to the upper left corner of the desktop.
 420 Return values
 421 none
 422 Description
 423 The function changes the position of an opened window. It does not have any effect on a fullscreen
 424 window.
 425 ")
 426
 427 (defcfun ("glfwGetWindowSize" %get-window-size) :void (width :pointer) (height :pointer))
 428 (defun get-window-size ()
 429   "The function is used for determining the size of an opened window. The returned values are dimensions
 430 of the client area of the window (i.e. excluding any window borders and decorations).
 431 (list width height)"
 432   (cffi:with-foreign-objects ((width :int)
 433                               (height :int))
 434     (%get-window-size width height)
 435     (list (mem-ref width :int)
 436           (mem-ref height :int))))
 437
 438 (defcfun+doc ("glfwSetWindowSizeCallback" set-window-size-callback) :void ((cbfun :pointer))
 439              "Parameters
 440 cbfun
 441       Pointer to a callback function that will be called every time the window size changes. The
 442       function should have the following C language prototype:
 443       void GLFWCALL functionname( int width, int height );
 444       Where functionname is the name of the callback function, and width and height are the
 445       dimensions of the window client area.
 446       If cbfun is NULL, any previously selected callback function will be deselected.
 447 Return values
 448 none
 449 Description
 450 The function selects which function to be called upon a window size change event.
 451 A window has to be opened for this function to have any effect.
 452 Notes
 453 Window size changes are recorded continuously, but only reported when glfwPollEvents,
 454 glfwWaitEvents or glfwSwapBuffers is called. ")
 455
 456 (defcfun+doc ("glfwIconifyWindow" iconify-window) :void ()
 457              "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
 458
 459 (defcfun+doc ("glfwRestoreWindow" restore-window) :void ()
 460              "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
 461 video mode will be restored.")
 462
 463 (defcfun+doc ("glfwGetWindowParam" get-window-param) :int ((param window-parameter))
 464 "Parameters
 465 param
 466       A token selecting which parameter the function should return (see table 3.2).
 467
 468 Return values
 469
 470 The function returns different parameters depending on the value of
 471 param. Table 3.2 lists valid param values, and their corresponding
 472 return values.
 473
 474 Description
 475 The function is used for acquiring various properties of an opened window.
 476
 477 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
 478 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
 479 the OpenGL renderer is a 3rd party renderer, rather than the fallback
 480 Microsoft software OpenGL renderer. In other words, it is not a real
 481 guarantee that the OpenGL renderer is actually hardware accelerated.
 482 ")
 483
 484 (defcfun+doc ("glfwSwapBuffers" swap-buffers) :void ()
 485              "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
 486 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
 487
 488
 489 (defcfun+doc ("glfwSwapInterval" swap-interval) :void ((interval :int))
 490              "Parameters
 491 interval
 492       Minimum number of monitor vertical retraces between each buffer swap performed by
 493       glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
 494       refresh of the monitor (also known as VSync off).
 495
 496 Description
 497
 498 The function selects the minimum number of monitor vertical retraces
 499 that should occur between two buffer swaps. If the selected swap
 500 interval is one, the rate of buffer swaps will never be higher than
 501 the vertical refresh rate of the monitor. If the selected swap
 502 interval is zero, the rate of buffer swaps is only limited by the
 503 speed of the software and the hardware.
 504
 505 Notes
 506
 507 This function will only have an effect on hardware and drivers that
 508 support user selection of the swap interval. ")
 509
 510
 511 (defcfun+doc ("glfwSetWindowRefreshCallback" set-window-refresh-callback) :void ((cbfun :pointer))
 512              "Parameters
 513 cbfun
 514        Pointer to a callback function that will be called when the window client area needs to be
 515        refreshed. The function should have the following CFFI  prototype:
 516        (cffi:defcallback callback-name :void ((width :int) (height :int)) .. body ..)
 517        Where callback is the name of the callback function.
 518        If cbfun is the null-pointer, any previously selected callback function will be deselected.
 519
 520 Description
 521
 522 The function selects which function to be called upon a window refresh
 523 event, which occurs when any part of the window client area has been
 524 damaged, and needs to be repainted (for instance, if a part of the
 525 window that was previously occluded by another window has become
 526 visible).  A window has to be opened for this function to have any
 527 effect.
 528
 529 Notes
 530 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
 531 glfwWaitEvents or glfwSwapBuffers is called.
 532 ")
 533
 534 (defcstruct vidmode
 535   (width :int)
 536   (height :int)
 537   (redbits :int)
 538   (bluebits :int)
 539   (greenbits :int))
 540
 541 (defcfun ("glfwGetVideoModes" %get-video-modes) :int (list :pointer) (maxcount :int))
 542
 543 (defun get-video-modes (&optional (maxcount 64))
 544   "Parameters
 545 maxcount
 546       Maximum number of video modes that list vector can hold.
 547
 548 Return values
 549 The function returns the number of detected video modes (this number will never exceed maxcount).
 550 The list vector is filled out with the video modes that are supported by the system.
 551
 552 Description
 553 The function returns a list of supported video modes. Each video mode is represented by a
 554 list of the form:
 555 (width height redbits greenbits bluebits)
 556
 557 Notes
 558 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
 559 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
 560   (with-foreign-object (list 'vidmode maxcount)
 561     (let ((count (%get-video-modes list maxcount)))
 562       (loop for i below count
 563          collecting
 564          (let ((mode (cffi:mem-aref list 'vidmode i)))
 565            (list (foreign-slot-value mode 'vidmode 'width)
 566                  (foreign-slot-value mode 'vidmode 'height)
 567                  (foreign-slot-value mode 'vidmode 'redbits)
 568                  (foreign-slot-value mode 'vidmode 'greenbits)
 569                  (foreign-slot-value mode 'vidmode 'bluebits)))))))
 570
 571 (defcfun ("glfwGetDesktopMode" %get-desktop-mode) :void (mode :pointer))
 572 (defun get-desktop-mode ()
 573   "Parameters
 574 mode
 575        Pointer to a GLFWvidmode structure, which will be filled out by the function.
 576 Return values
 577 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
 578 Description
 579 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
 580 for a definition of the GLFWvidmode structure.
 581 Notes
 582 The color depth of the desktop display is always reported as the number of bits for each individual color
 583 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
 584 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
 585 adds up to 8 bits in total.
 586 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
 587 differ from the desktop video mode if the GLFW window is a fullscreen window).
 588 "
 589   (with-foreign-object (mode 'vidmode)
 590     (%get-desktop-mode mode)
 591     (list (foreign-slot-value mode 'vidmode 'width)
 592           (foreign-slot-value mode 'vidmode 'height)
 593           (foreign-slot-value mode 'vidmode 'redbits)
 594           (foreign-slot-value mode 'vidmode 'greenbits)
 595           (foreign-slot-value mode 'vidmode 'bluebits))))
 596
 597 (defcfun+doc ("glfwPollEvents" poll-events) :void ()
 598              "Description
 599 The function is used for polling for events, such as user input and window resize events. Upon calling
 600 this function, all window states, keyboard states and mouse states are updated. If any related callback
 601 functions are registered, these are called during the call to glfwPollEvents.
 602
 603 Notes
 604 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
 605 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
 606 no need to call glfwPollEvents.
 607 ")
 608
 609 (defcfun+doc ("glfwWaitEvents" wait-events) :void ()
 610              "Description
 611 The function is used for waiting for events, such as user input and window resize events. Upon calling
 612 this function, the calling thread will be put to sleep until any event appears in the event queue. When
 613 events are ready, the events will be processed just as they are processed by glfwPollEvents.
 614 If there are any events in the queue when the function is called, the function will behave exactly like
 615 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
 616
 617 Notes
 618 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
 619 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
 620 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
 621 assumptions about when or why glfw::WaitEvents will return.
 622 ")
 623
 624 (defcfun+doc ("glfwGetKey" get-key) :boolean ((key key-code))
 625              "Parameters
 626 key
 627       A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
 628       character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
 629       identifiers.
 630 Return values
 631 The function returns T if the key is held down, or NIL if the key is not
 632 held down.
 633
 634 Description
 635 The function queries the current state of a specific keyboard key. The physical location of each key
 636 depends on the system keyboard layout setting.
 637
 638 Notes
 639 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
 640 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
 641 layouts, they may not be available on other keyboard layouts.
 642 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
 643 control), the left version is used (e.g. +KEY_LSHIFT+)
 644 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
 645 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
 646 glfw::GetKey.
 647 ")
 648
 649 (defcfun+doc ("glfwGetMouseButton" get-mouse-button) :int ((button :int))
 650              "Parameters
 651 button
 652       A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
 653 Return values
 654 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
 655 mouse button is not held down.
 656 Description
 657 The function queries the current state of a specific mouse button.
 658 Notes
 659 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
 660 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
 661 glfw::GetMouseButton.
 662 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
 663 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
 664 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
 665 ")
 666
 667
 668 (defcfun+out+doc ("glfwGetMousePos" get-mouse-pos) :void ((:out xpos :int) (:out ypos :int))
 669                  "Return values
 670 The function returns the current mouse position in xpos and ypos.
 671
 672 Description
 673 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
 674 cursor position, relative to the upper left corner of the window and limited to the client area of the
 675 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
 676 boundaries except to those implied by the maximum number that can be represented by a signed integer
 677 (normally -2147483648 to +2147483647).
 678
 679 Notes
 680 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
 681 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
 682 glfw::GetMousePos.
 683 ")
 684
 685
 686 (defcfun+doc ("glfwSetMousePos" set-mouse-pos) :void ((xpos :int) (ypos :int))
 687              "Parameters
 688 xpos
 689      Horizontal position of the mouse.
 690 ypos
 691      Vertical position of the mouse.
 692
 693 Description
 694 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
 695 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
 696 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
 697 ")
 698
 699 (defcfun+doc ("glfwGetMouseWheel" get-mouse-wheel) :int ()
 700              "Return values
 701 The function returns the current mouse wheel position.
 702 Description
 703 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
 704 mouse axis, which is available as a separate wheel or up/down stick on some mice.
 705 Notes
 706 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
 707 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
 708 glfw::GetMouseWheel.
 709 ")
 710
 711 (defcfun+doc ("glfwSetMouseWheel" set-mouse-wheel) :void ((pos :int))
 712              "Parameters
 713 pos
 714      Position of the mouse wheel.
 715 Description
 716 The function changes the position of the mouse wheel.
 717 ")
 718
 719
 720 (defcfun+doc ("glfwSetKeyCallback" set-key-callback) :void ((cbfun :pointer))
 721              "Parameters
 722 cbfun
 723       Pointer to a callback function that will be called every time a key is pressed or released. The
 724       function should have the following C language prototype:
 725       void GLFWCALL functionname( int key, int action );
 726       Where functionname is the name of the callback function, key is a key identifier, which is an
 727       uppercase printable ISO 8859-1 character or a special key identifier (see table 3.3), and action is
 728       either +PRESS+ or +RELEASE+
 729       If cbfun is NULL, any previously selected callback function will be deselected.
 730 Return values
 731 none
 732 Description
 733 The function selects which function to be called upon a keyboard key event. The callback function is
 734 called every time the state of a single key is changed (from released to pressed or vice versa). The
 735 reported keys are unaffected by any modifiers (such as shift or alt).
 736 A window has to be opened for this function to have any effect.
 737 Notes
 738 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
 739 or glfw::SwapBuffers is called.
 740 ")
 741 (defcfun+doc ("glfwSetCharCallback" set-char-callback) :void ((cbfun :pointer))
 742              "Parameters
 743 cbfun
 744        Pointer to a callback function that will be called every time a printable character is generated by
 745        the keyboard. The function should have the following C language prototype:
 746        void GLFWCALL functionname( int character, int action );
 747        Where functionname is the name of the callback function, character is a Unicode (ISO 10646)
 748        character, and action is either +PRESS+ or +RELEASE+
 749        If cbfun is NULL, any previously selected callback function will be deselected.
 750 Return values
 751 none
 752 Description
 753 The function selects which function to be called upon a keyboard character event. The callback function
 754 is called every time a key that results in a printable Unicode character is pressed or released. Characters
 755 are affected by modifiers (such as shift or alt).
 756 A window has to be opened for this function to have any effect.
 757 Notes
 758 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
 759 or glfw::SwapBuffers is called.
 760 Control characters, such as tab and carriage return, are not reported to the character callback function,
 761 since they are not part of the Unicode character set. Use the key callback function for such events (see
 762 glfw::SetKeyCallback).
 763 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
 764 eight bit data type (e.g. the C language char type) without first checking that the character code is less
 765 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
 766 ")
 767 (defcfun+doc ("glfwSetMouseButtonCallback" set-mouse-button-callback) :void ((cbfun :pointer))
 768              "Parameters
 769 cbfun
 770       Pointer to a callback function that will be called every time a mouse button is pressed or released.
 771       The function should have the following C language prototype:
 772       void GLFWCALL functionname( int button, int action );
 773       Where functionname is the name of the callback function, button is a mouse button identifier (see
 774       table 3.4 on page 56), and action is either +PRESS+ or +RELEASE+
 775       If cbfun is NULL, any previously selected callback function will be deselected.
 776 Return values
 777 none
 778 Description
 779 The function selects which function to be called upon a mouse button event.
 780 A window has to be opened for this function to have any effect.
 781 Notes
 782 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
 783 glfw::WaitEvents or glfw::SwapBuffers is called.
 784 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
 785 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
 786 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
 787 ")
 788 (defcfun+doc ("glfwSetMousePosCallback" set-mouse-pos-callback) :void ((cbfun :pointer))
 789              "Parameters
 790 cbfun
 791       Pointer to a callback function that will be called every time the mouse is moved. The function
 792       should have the following C language prototype:
 793       void GLFWCALL functionname( int x, int y );
 794       Where functionname is the name of the callback function, and x and y are the mouse coordinates
 795       (see glfw::GetMousePos for more information on mouse coordinates).
 796       If cbfun is NULL, any previously selected callback function will be deselected.
 797 Return values
 798 none
 799 Description
 800 The function selects which function to be called upon a mouse motion event.
 801 A window has to be opened for this function to have any effect.
 802 Notes
 803 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
 804 glfw::WaitEvents or glfw::SwapBuffers is called.
 805 ")
 806 (defcfun+doc ("glfwSetMouseWheelCallback" set-mouse-wheel-callback) :void ((cbfun :pointer))
 807              "Parameters
 808 cbfun
 809       Pointer to a callback function that will be called every time the mouse wheel is moved. The
 810       function should have the following C language prototype:
 811       void GLFWCALL functionname( int pos );
 812       Where functionname is the name of the callback function, and pos is the mouse wheel position.
 813       If cbfun is NULL, any previously selected callback function will be deselected.
 814 Return values
 815 none
 816 Description
 817 The function selects which function to be called upon a mouse wheel event.
 818 A window has to be opened for this function to have any effect.
 819 Notes
 820 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
 821 glfw::WaitEvents or glfw::SwapBuffers is called.
 822 ")
 823
 824 (defcfun+doc ("glfwGetJoystickParam" get-joystick-param) :int ((joy :int) (param joystick-param-token))
 825              "Parameters
 826 joy
 827       A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
 828 param
 829       A token selecting which parameter the function should return (see table 3.5).
 830 Return values
 831 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
 832 values, and their corresponding return values.
 833 Description
 834 The function is used for acquiring various properties of a joystick.
 835 Notes
 836 The joystick information is updated every time the function is called.
 837 No window has to be opened for joystick information to be valid.
 838 ")
 839
 840 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
 841
 842 (defun get-joystick-pos (joy numaxes)
 843   "Parameters
 844 joy
 845        A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
 846 numaxes
 847        Specifies how many axes should be returned.
 848 Return values
 849        An list that will hold the positional values for all requested axes.
 850 If the joystick is not supported or connected, the function will
 851 return nil.
 852
 853 Description
 854 The function queries the current position of one or more axes of a joystick. The positional values are
 855 returned in an array, where the first element represents the first axis of the joystick (normally the X
 856 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
 857 right, forward or up, and the negative direction is left, back or down.
 858 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
 859 unused elements in the pos array will be set to 0.0 (zero).
 860
 861 Notes
 862 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
 863 or glfw::WaitEvents for joystick state to be updated.
 864 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
 865 supported axes.
 866 No window has to be opened for joystick input to be valid.
 867 "
 868   (with-foreign-object (pos :float numaxes)
 869     (let ((numaxes (%get-joystick-pos joy pos numaxes)))
 870       (loop for i below numaxes collecting (mem-aref pos :float i)))))
 871
 872
 873 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
 874 (defun get-joystick-buttons (joy numbuttons)
 875   "Parameters
 876 joy
 877        A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
 878 numbuttons
 879        Specifies how many buttons should be returned.
 880 Return values
 881        A list that will hold the button states for all requested buttons.
 882 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
 883 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
 884 function will return 0 (zero).
 885
 886 Description
 887 The function queries the current state of one or more buttons of a joystick. The button states are
 888 returned in an array, where the first element represents the first button of the joystick. Each state can be
 889 either +PRESS+ or +RELEASE+
 890 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
 891 available, the unused elements in the buttons array will be set to +RELEASE+
 892
 893 Notes
 894 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
 895 or glfw::WaitEvents for joystick state to be updated.
 896 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
 897 supported buttons.
 898 No window has to be opened for joystick input to be valid.
 899 "
 900   (with-foreign-object (buttons :unsigned-char numbuttons)
 901     (let ((numbuttons (%get-joystick-buttons joy buttons numbuttons)))
 902       (loop for i below numbuttons collecting (mem-aref buttons :unsigned-char i)))))
 903
 904
 905 (defcfun+doc ("glfwGetTime" get-time) :double ()
 906              "Return values
 907 The function returns the value of the high precision timer. The time is measured in seconds, and is
 908 returned as a double precision floating point value.
 909
 910 Description
 911 The function returns the state of a high precision timer. Unless the timer has been set by the
 912 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
 913 was called.
 914
 915 Notes
 916 The resolution of the timer depends on which system the program is running on. The worst case
 917 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
 918 than 1us.
 919 ")
 920
 921 (defcfun+doc ("glfwSetTime" set-time) :void ((time :double))
 922              "Parameters
 923 time
 924       Time (in seconds) that the timer should be set to.
 925
 926 Description
 927 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
 928 glfw::GetTime will be relative to this time. The time is given in seconds.
 929 ")
 930
 931 (defcfun+doc ("glfwSleep" sleep) :void ((time :double))
 932              "Parameters
 933 time
 934         Time, in seconds, to sleep.
 935
 936 Description
 937 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
 938 put to sleep. Other threads within the same process can still execute.
 939
 940 Notes
 941 There is usually a system dependent minimum time for which it is possible to sleep. This time is
 942 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
 943 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
 944 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
 945 latter should only happen when very short sleep times are specified, if at all. ")
 946
 947 (defcstruct image
 948   (width :int)
 949   (height :int)
 950   (format :int)
 951   (bytes-per-pixel :int)
 952   (data :pointer))
 953
 954 (defun make-bitfield (enum-name attributes)
 955   (apply #'logior 0 (mapcar (lambda (x)
 956                               (foreign-enum-value enum-name x))
 957                             attributes)))
 958
 959 (defcfun ("glfwReadImage" %read-image) boolean
 960   (name :string) (img image) (flags :int))
 961 (defun read-image (name image &rest flags)
 962   "Parameters
 963 name
 964       A null terminated ISO 8859-1 string holding the name of the file that should be read.
 965 img
 966       Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
 967       read was successful).
 968 flags
 969       Flags for controlling the image reading process. Valid flags are listed in table 3.6
 970 Return values
 971 The function returns t if the image was loaded successfully. Otherwise nil is
 972 returned.
 973 Description
 974 The function reads an image from the file specified by the parameter name and returns the image
 975 information and data in a GLFWimage structure, which has the following definition:
 976
 977 typedef struct {
 978       int Width, Height;                 //   Image dimensions
 979       int Format;                        //   OpenGL pixel format
 980       int BytesPerPixel;                 //   Number of bytes per pixel
 981       unsigned char *Data;               //   Pointer to pixel data
 982 } GLFWimage;
 983
 984 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
 985 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
 986 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
 987
 988 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
 989 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
 990 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
 991 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
 992 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
 993 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
 994
 995 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
 996 Notes
 997 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
 998 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
 999 Paletted images are translated into true color or true color + alpha pixel formats.
1000 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1001 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1002 "
1003   (%read-image name image (make-bitfield 'image-flag flags)))
1004
1005 (defcfun ("glfwReadMemoryImage" %read-memory-image) boolean
1006   (data :pointer) (size :long) (img image) (flags :int))
1007 (defun read-memory-image (data size image &rest flags)
1008   "Parameters
1009 data
1010       The memory buffer holding the contents of the file that should be read.
1011 size
1012       The size, in bytes, of the memory buffer.
1013 img
1014       Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1015       read was successful).
1016 flags
1017       Flags for controlling the image reading process. Valid flags are listed in table 3.6
1018 Return values
1019 The function returns t if the image was loaded successfully. Otherwise nil is
1020 returned.
1021 Description
1022 The function reads an image from the memory buffer specified by the parameter data and returns the
1023 image information and data in a GLFWimage structure, which has the following definition:
1024
1025 typedef struct {
1026       int Width, Height;                 //   Image dimensions
1027       int Format;                        //   OpenGL pixel format
1028       int BytesPerPixel;                 //   Number of bytes per pixel
1029       unsigned char *Data;               //   Pointer to pixel data
1030 } GLFWimage;
1031
1032 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1033 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1034 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1035
1036 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1037 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1038 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1039 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1040 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1041 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1042 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1043 Notes
1044 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1045 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1046 alpha.
1047 Paletted images are translated into true color or true color + alpha pixel formats.
1048 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1049 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1050 "
1051   (%read-memory-image data size image (make-bitfield 'image-flag flags)))
1052
1053 (defcfun+doc ("glfwFreeImage" free-image) :void ((img image))
1054              "Parameters
1055 img
1056      Pointer to a GLFWimage struct.
1057 Description
1058 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1059 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1060 this function, once the image is not needed anymore. ")
1061
1062 (defcfun ("glfwLoadTexture2D" %load-texture-2d) boolean (name :string) (flags :int))
1063 (defun load-texture-2d (name &rest flags)
1064   "Parameters
1065 name
1066        An ISO 8859-1 string holding the name of the file that should be loaded.
1067 flags
1068        Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1069 Return values
1070 The function returns t if the texture was loaded successfully. Otherwise nil is
1071 returned.
1072
1073 Description
1074
1075 The function reads an image from the file specified by the parameter
1076 name and uploads the image to OpenGL texture memory (using the
1077 glTexImage2D function).  If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1078 all mipmap levels for the loaded texture are generated and uploaded to
1079 texture memory.  Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1080 the texture is the lower left corner of the loaded image. If the flag
1081 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1082 corner.  For single component images (i.e. gray scale), the texture is
1083 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1084 otherwise it is uploaded as a luminance texture.
1085
1086 Notes
1087 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1088 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1089 alpha.
1090 Paletted images are translated into true color or true color + alpha pixel formats.
1091 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1092 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1093 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1094 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1095 generated by GLFW in software.
1096
1097 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1098 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1099 texture is a single component texture. The red, green and blue components are set to 1.0.
1100 "
1101   (%load-texture-2d name (make-bitfield 'image-flag flags)))
1102
1103 (defcfun ("glfwLoadMemoryTexture2D" %load-memory-texture-2d) boolean
1104   (data :pointer) (size :long) (flags :int))
1105 (defun load-memory-texture-2d (data size &rest flags)
1106   "Parameters
1107 data
1108        The memory buffer holding the contents of the file that should be loaded.
1109 size
1110        The size, in bytes, of the memory buffer.
1111 flags
1112        Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1113 Return values
1114 The function returns t if the texture was loaded successfully. Otherwise nil is
1115 returned.
1116
1117 Description
1118 The function reads an image from the memory buffer specified by the parameter data and uploads the
1119 image to OpenGL texture memory (using the glTexImage2D function).
1120 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1121 generated and uploaded to texture memory.
1122 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1123 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1124 corner.
1125 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1126 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1127
1128 Notes
1129 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1130 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1131 + alpha.
1132 Paletted images are translated into true color or true color + alpha pixel formats.
1133 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1134 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1135 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1136 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1137 generated by GLFW in software.
1138
1139 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1140 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1141 texture is a single component texture. The red, green and blue components are set to 1.0.
1142 "
1143   (%load-memory-texture-2d data size (make-bitfield 'image-flags flags)))
1144
1145
1146 (defcfun ("glfwLoadTextureImage2D" %load-texture-image-2d) boolean
1147   (img image) (flags :int))
1148 (defun load-texture-image-2d (image &rest flags)
1149   "Parameters
1150 img
1151       Pointer to a GLFWimage struct holding the information about the image to be loaded.
1152 flags
1153       Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1154 Return values
1155 The function returns t if the texture was loaded successfully. Otherwise nil is
1156 returned.
1157
1158 Description
1159 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1160 the glTexImage2D function).
1161 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1162 generated and uploaded to texture memory.
1163 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1164 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1165 corner.
1166 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1167 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1168
1169 Notes
1170 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1171 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1172 + alpha.
1173 Paletted images are translated into true color or true color + alpha pixel formats.
1174 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1175 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1176 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1177 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1178 generated by GLFW in software.
1179
1180 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1181 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1182 texture is a single component texture. The red, green and blue components are set to 1.0. "
1183   (%load-texture-image-2d image (make-bitfield 'image-flag flags)))
1184
1185
1186 (defcfun+doc ("glfwExtensionSupported" extension-supported) boolean ((extension :string))
1187              "Parameters
1188 extension
1189       A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1190 Return values
1191 The function returns t if the extension is supported. Otherwise it returns nil.
1192 Description
1193 The function does a string search in the list of supported OpenGL extensions to find if the specified
1194 extension is listed.
1195 Notes
1196
1197 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1198 must have been opened with glfwOpenWindow).
1199 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1200 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1201 System.
1202 ")
1203
1204 (defcfun+doc ("glfwGetProcAddress" get-proc-address) :pointer ((procname :string))
1205              "Parameters
1206 procname
1207        A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1208 Return values
1209 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1210 NULL is returned.
1211 Description
1212 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1213 extensions define new API functions, which are usually not available through normal linking. It is
1214 therefore necessary to get access to those API functions at runtime.
1215 Notes
1216
1217 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1218 must have been opened with glfwOpenWindow).
1219 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1220 will always return NULL.
1221 ")
1222
1223 (defcfun+out+doc ("glfwGetGLVersion" get-gl-version) :void ((:out major :int)
1224                                                             (:out minor :int)
1225                                                             (:out rev :int))
1226                  "Return values
1227 The function returns the major and minor version numbers and the revision for the currently used
1228 OpenGL implementation as a list (major minor rev).
1229
1230 Description
1231 The function returns the OpenGL implementation version. This is a convenient function that parses
1232 the version number information from the string returned by calling
1233 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1234 what functionality is supported by the used OpenGL implementation.
1235
1236 Notes
1237 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1238 must have been opened with glfwOpenWindow). ")
1239
1240 (defctype thread :int)
1241 (defctype threadfun :pointer)
1242 (defctype mutex :pointer)
1243 (defctype cond :pointer)
1244
1245 (defcfun+doc ("glfwCreateThread" create-thread) thread ((fun threadfun) (arg :pointer) )
1246 "Parameters
1247 fun
1248       A pointer to a function that acts as the entry point for the new thread. The function should have
1249       the following C language prototype:
1250       void GLFWCALL functionname( void *arg );
1251       Where functionname is the name of the thread function, and arg is the user supplied argument
1252       (see below).
1253 arg
1254       An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1255       pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1256 Return values
1257 The function returns a thread identification number if the thread was created successfully. This number
1258 is always positive. If the function fails, a negative number is returned.
1259 Description
1260 The function creates a new thread, which executes within the same address space as the calling process.
1261 The thread entry point is specified with the fun argument.
1262 Once the thread function fun returns, the thread dies.
1263 Notes
1264 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1265 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1266 ")
1267 (defcfun+doc ("glfwDestroyThread" destroy-thread) :void ((id thread))
1268 "Parameters
1269 ID
1270       A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1271 Description
1272 The function kills a running thread and removes it from the thread list.
1273 Notes
1274 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1275 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1276 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1277 ")
1278 (defcfun+doc ("glfwWaitThread" wait-thread) boolean ((id thread) (wait-mode wait-mode) )
1279 "Parameters
1280 ID
1281       A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1282 waitmode
1283       Can be either +WAIT+ or +NOWAIT+
1284 Return values
1285 The function returns t if the specified thread died after the function was called, or the thread
1286 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1287 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1288 running.
1289 ")
1290 (defcfun+doc ("glfwGetThreadID" get-thread-id) thread ()
1291 "Return values
1292 The function returns a thread identification handle for the calling thread.
1293 Description
1294 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1295 by glfw::CreateThread when the thread was created.
1296 ")
1297
1298 (defcfun+doc ("glfwCreateMutex" create-mutex) mutex ()
1299 "Return values
1300 The function returns a mutex handle, or NULL if the mutex could not be created.
1301 Description
1302 The function creates a mutex object, which can be used to control access to data that is shared between
1303 threads.
1304 ")
1305 (defcfun+doc ("glfwDestroyMutex" destroy-mutex) :void ((mutex mutex))
1306 "Parameters
1307 mutex
1308       A mutex object handle.
1309 Description
1310 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1311 used by any thread.
1312 ")
1313 (defcfun+doc ("glfwLockMutex" lock-mutex) :void ((mutex mutex))
1314 "Parameters
1315 mutex
1316       A mutex object handle.
1317 Description
1318 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1319 thread, the function will block the calling thread until it is released by the locking thread. Once the
1320 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1321 glfw::UnlockMutex.
1322 ")
1323 (defcfun+doc ("glfwUnlockMutex" unlock-mutex) :void ((mutex mutex))
1324 "Parameters
1325 mutex
1326       A mutex object handle.
1327 Description
1328 The function releases the lock of a locked mutex object.
1329 ")
1330
1331 (defmacro with-lock-mutex (mutex &body forms)
1332   "Parameters
1333 mutex
1334       A mutex object handle.
1335 forms
1336       Body of code to execute
1337 Description
1338 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1339 using glfw::UnlockMutex.
1340 So, forms will not execute until an exclusive lock is held.
1341 The lock is then released when the stack is unwound."
1342   (let ((smutex (gensym "MUTEX-")))
1343     `(let ((,smutex ,mutex))
1344        (glfw:lock-mutex ,smutex)
1345        (unwind-protect (progn ,@forms)
1346          (glfw:unlock-mutex ,smutex)))))
1347
1348 (defcfun+doc ("glfwCreateCond" create-cond) cond ()
1349 "Return values
1350 The function returns a condition variable handle, or NULL if the condition variable could not be
1351 created.
1352 Description
1353 The function creates a condition variable object, which can be used to synchronize threads.
1354 ")
1355 (defcfun+doc ("glfwDestroyCond" destroy-cond) :void ((cond cond))
1356 "Parameters
1357 cond
1358       A condition variable object handle.
1359 Description
1360 The function destroys a condition variable object. After a condition variable object has been destroyed,
1361 it may no longer be used by any thread.
1362 ")
1363 (defcfun+doc ("glfwWaitCond" wait-cond) :void ((cond cond) (mutex mutex) (timeout :double))
1364 "  arameters
1365 cond
1366        A condition variable object handle.
1367 mutex
1368        A mutex object handle.
1369 timeout
1370        Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1371        seconds), or +INFINITY+
1372 Description
1373 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1374 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1375 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1376 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1377 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1378 Notes
1379 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1380 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1381 prepares to wait on a condition variable and another thread signals the condition just before the first
1382 thread actually waits on it.
1383 ")
1384 (defcfun+doc ("glfwSignalCond" signal-cond) :void ((cond cond))
1385 "Parameters
1386 cond
1387        A condition variable object handle.
1388 Description
1389 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1390 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1391 is not specified which.
1392 Notes
1393 When several threads are waiting for the condition variable, which thread is started depends on
1394 operating system scheduling rules, and may vary from system to system and from time to time.
1395 ")
1396 (defcfun+doc ("glfwBroadcastCond" broadcast-cond) :void ((cond cond))
1397 "Parameters
1398 cond
1399       A condition variable object handle.
1400 Description
1401 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1402 waiting on cond, nothing happens.
1403 Notes
1404 When several threads are waiting for the condition variable, the order in which threads are started
1405 depends on operating system scheduling rules, and may vary from system to system and from time to
1406 time.
1407 ")
1408
1409 (defcfun+doc ("glfwGetNumberOfProcessors" get-number-of-processors) :int ()
1410 "Return values
1411 The function returns the number of active processors in the system.
1412 Description
1413 The function determines the number of active processors in the system.
1414 Notes
1415 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1416 Threading) processors, will report the number of logical processors.
1417 ")
1418 (defcfun+doc ("glfwEnable" enable) :void ((token boolean-token))
1419              "Parameters
1420 token
1421        A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1422 Return values
1423 none
1424 Description
1425 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1426 description of each feature.
1427 +AUTO_POLL_EVENTS+
1428 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1429 that glfw::SwapBuffers is called.
1430 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1431 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1432 function, since calling glfw::PollEvents from a callback function is not allowed.
1433 +KEY_REPEAT+
1434 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1435 when a key is held down long enough (according to the system key repeat configuration).
1436 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1437 when a key is pressed (and once when it is released).
1438 +MOUSE_CURSOR+
1439 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1440 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1441 the client area of the window.
1442 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1443 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1444 from the mouse, without being restricted or manipulated by the windowing system.
1445 +STICKY_KEYS+
1446 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1447 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1448 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1449 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1450 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1451 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1452 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1453 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1454 all keys.
1455 +STICKY_MOUSE_BUTTONS+
1456 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1457 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1458 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1459 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1460 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1461 glfw::GetMouseButton will never be released. Note also that enabling
1462 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1463 functionality.
1464 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1465 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1466 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1467 +SYSTEM_KEYS+
1468 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1469 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1470 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1471 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1472 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1473 the GLFW video mode again.
1474 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1475 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1476 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1477 ")
1478 (defcfun+doc ("glfwDisable" disable) :void ((token boolean-token))
1479              "Parameters
1480 token
1481        A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1482 Return values
1483 none
1484 Description
1485 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1486 description of each feature.
1487 +AUTO_POLL_EVENTS+
1488 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1489 that glfw::SwapBuffers is called.
1490 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1491 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1492 function, since calling glfw::PollEvents from a callback function is not allowed.
1493 +KEY_REPEAT+
1494 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1495 when a key is held down long enough (according to the system key repeat configuration).
1496 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1497 when a key is pressed (and once when it is released).
1498 +MOUSE_CURSOR+
1499 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1500 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1501 the client area of the window.
1502 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1503 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1504 from the mouse, without being restricted or manipulated by the windowing system.
1505 +STICKY_KEYS+
1506 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1507 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1508 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1509 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1510 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1511 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1512 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1513 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1514 all keys.
1515 +STICKY_MOUSE_BUTTONS+
1516 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1517 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1518 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1519 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1520 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1521 glfw::GetMouseButton will never be released. Note also that enabling
1522 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1523 functionality.
1524 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1525 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1526 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1527 +SYSTEM_KEYS+
1528 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1529 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1530 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1531 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1532 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1533 the GLFW video mode again.
1534 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1535 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1536 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1537 ")