<h1>GLFW Bindings</h1>

<h2>Synopsis</h2>

<code>(import (system glfw))</code>

Bindings to the library.

<h2>Conditions</h2>

<h3>condition:
<h3>procedure: <code>(glfw-condition?
<h3>procedure: <code>(make-glfw-condition <i>message</i>
<h3>procedure: <code>(glfw-condition-code

The <tt>&glfw</tt> condition type is derived from <tt>&message</tt> and stores an error code together with a human-readable message.

<h3>parameter:

The binding automatically registers a GLFW error callback that stores the last encountered error in this parameter as a <tt>&glfw</tt> condition.

<h2>Initialization</h2>

<h3>procedure:

Initializes the GLFW library. This procedure is implicitly called when the binding library body is executed and only has to be called manually if the library is later terminated and needs to be initialized again. However, calling the procedure multiple times is harmless.

<h3>procedure:

Terminates the GLFW library and destroys all windows and cursors.

<h2>Monitors</h2>

<h3>procedure: <code>(monitor?

Checks whether the given object is a GLFW monitor.

<h3>procedure:

Returns the primary monitor.

<h3>procedure:

Returns a list of all currently attached monitors.

<h3>procedure: <code>(monitor-name

Retrieves the name of the given monitor.

<h3>procedure: <code>(monitor-position

Retrieves the horizontal and vertical position of the monitor's upper left corner in the virtual screen coordinate space.

<h3>procedure: <code>(monitor-size

Retrieves the horizontal and vertical size of the monitor in virtual screen coordinates.

<h3>procedure: <code>(monitor-size/mm

Retrieves the horizontal and vertical physical size of the monitor in millimeters.

<h2>Video Modes</h2>

<h3>record:
<h3>procedure: <code>(video-mode?
<h3>procedure: <code>(make-video-mode <i>width</i> <i>height</i> <i>red-bits</i> <i>green-bits</i> <i>blue-bits</i>
<h3>procedure: <code>(video-mode-width
<h3>procedure: <code>(video-mode-height
<h3>procedure: <code>(video-mode-red-bits
<h3>procedure: <code>(video-mode-green-bits
<h3>procedure: <code>(video-mode-blue-bits
<h3>procedure: <code>(video-mode-refresh-rate

A record type representing a video mode. Instances are serializable.

<h3>procedure: <code>(monitor-video-mode

Retrieves the current video mode of the given monitor.

<h2>Window Hints</h2>

<h3>record:
<h3>procedure: <code>(window-hints?
<h3>procedure: <code>(make-window-hints <i>arg</i>
<h3>procedure: <code>(window-hints-alpha-bits
<h3>procedure: <code>(window-hints-depth-bits
<h3>procedure: <code>(window-hints-stencil-bits
<h3>procedure: <code>(window-hints-samples
<h3>procedure: <code>(window-hints-stereo?
<h3>procedure: <code>(window-hints-double-buffer?
<h3>procedure: <code>(window-hints-context-api
<h3>procedure: <code>(window-hints-context-version
<h3>procedure: <code>(window-hints-resizable?
<h3>procedure: <code>(window-hints-visible?
<h3>procedure: <code>(window-hints-decorated?
<h3>procedure: <code>(window-hints-focused?
<h3>procedure: <code>(window-hints-auto-iconify?
<h3>procedure: <code>(window-hints-floating?

Window hints are represented as records extending video modes. Instances are serializable.

Instances may be constructed from any combination of monitor handles, video modes, existing window hints or field name symbols followed by values. Later constructor arguments override the values of earlier ones. The value <tt>#f</tt> by itself is ignored in the argument list.

<h3>parameter:

The window hints to be used in the construction of new windows are stored in a parameter. The parameter may be set to a monitor, video mode or window hints instance. When queried, the parameter always returns a window hints instance. When the parameter is set, the appropriate native GLFW window hints are also set. When the parameter is set to <tt>#f</tt>, the native window hints are reset to their default values.

<h2>Windows</h2>

<h3>procedure: <code>(window?

Checks whether the given object is a GLFW window.

<h3>procedure: <code>(make-window <i>proc</i> <i>title</i> <i>width</i> <i>height</i> <i>monitor</i>
<h3>procedure: <code>(make-window <i>proc</i> <i>title</i> <i>width</i> <i>height</i>
<h3>procedure: <code>(make-window <i>proc</i> <i>title</i> <i>width</i>
<h3>procedure: <code>(make-window <i>proc</i> <i>title</i>
<h3>procedure: <code>(make-window <i>proc</i>

Creates a new window. The given procedure is called to handle events (see below under "Events") and is passed to <tt>lock-object</tt> before it is stored in the native window.

If the width or height are not given or <tt>#f</tt>, their values are taken from the current window hints.

If only a monitor is given instead of width and height, the window hints are adapted for a fullscreen window using the monitor's current video mode. The window hints are restored to their previous state afterwards.

<h3>procedure: <code>(destroy-window <i>window</i>
<h3>procedure: <code>(destroy-window

Destroys the given window. Iff the <tt>unlock?</tt> argument is given and not <tt>#f</tt>, the callback procedure of the window is passed to <tt>unlock-object</tt>.

<h3>procedure: <code>(window-monitor

Retrieves the monitor that currently displays the given window.

<h3>procedure: <code>(window-context-api

Retrieves the supported client API of the window's graphics context. The result may differ from the API specified in the window hints, but only if it subsumes the API specified in the window hints.

<h3>procedure: <code>(window-context-version

Retrieves the version of the client API supported by the window's graphics context as a pair of two integers.

<h3>procedure: <code>(window-title-set! <i>window</i>

Changes the title of a window.

<h3>procedure: <code>(window-position
<h3>procedure: <code>(window-position-set! <i>window</i> <i>x</i>

Access the horizontal and vertical position of the window's client area in the virtual screen coordinate space.

<h3>procedure: <code>(window-size
<h3>procedure: <code>(window-size-set! <i>window</i> <i>x</i>

Access the horizontal and vertical size of the window's client area in virtual screen coordinates.

<h3>procedure: <code>(window-framebuffer-size

Retrieves the horizontal and vertical size of the window's framebuffer in pixels.

<h3>procedure: <code>(window-frame-size

Retrieves the left, top, right and bottom window decoration sizes in virtual screen coordinates.

<h3>procedure: <code>(window-should-close?
<h3>procedure: <code>(window-should-close-set! <i>window</i>

Access the window close flag.

<h3>procedure: <code>(window-iconified?
<h3>procedure: <code>(window-iconified-set! <i>window</i>

Access the window iconification state.

<h3>procedure: <code>(window-visible?
<h3>procedure: <code>(window-visible-set! <i>window</i>

Access the window visibility state.

<h3>procedure: <code>(window-resizable?

Checks whether the window is resizable by the user.

<h3>procedure: <code>(window-decorated?

Checks whether the window has decorations.

<h3>procedure: <code>(window-floating?

Checks whether the window is floating.

<h3>procedure: <code>(window-focused?

Checks whether the window has the input focus.

<h3>parameter:

The window with the currently active rendering context, or <tt>#f</tt>.

<h3>procedure: <code>(extension-supported?

Determines whether the given client API extension is supported by the current context.

<h3>procedure: <code>(extension-entry

Retrieves the entry point of the given client API extension procedure for the current context.

<h3>procedure: <code>(set-swap-interval!

Set the number of synchronization intervals to wait for buffer swaps of the current context window.

<h3>procedure: <code>(window-swap-buffers!

Swaps the back and front buffers of the given window.

<h2>Clipboard</h2>

<h3>procedure: <code>(window-clipboard
<h3>procedure: <code>(window-clipboard-set! <i>window</i>

Access the text content of the clipboard for the given window.

<h2>Cursors</h2>

<h3>procedure: <code>(cursor?

Checks whether the given object is a GLFW cursor.

<h3>ftype:

Foreign structure type for custom images.

<h3>procedure: <code>(make-cursor
<h3>procedure: <code>(make-cursor <i>image</i> <i>hot-x</i>

Creates a new cursor. The image may be a pointer to a custom image structure, in which case you can also specify a hotspot position in the cursor image, defaulting to the top left corner.

Alternatively you can create a predefined cursor given one of the symbols <tt>arrow</tt>, <tt>ibeam</tt>, <tt>i-beam</tt>, <tt>crosshair</tt>, <tt>hand</tt>, <tt>hresize</tt>, <tt>h-resize</tt>, <tt>vresize</tt> or <tt>v-resize</tt>.

<h3>procedure: <code>(window-cursor-set! <i>window</i>

Sets the cursor for the given window, or restores the default if the cursor is <tt>#f</tt>.

<h3>procedure: <code>(window-cursor-mode
<h3>procedure: <code>(window-cursor-mode-set! <i>window</i>

Access the cursor mode of the window, which is one of the symbols <tt>normal</tt>, <tt>hidden</tt> or <tt>disabled</tt>.

<h3>procedure: <code>(window-cursor-position
<h3>procedure: <code>(window-cursor-position-set! <i>window</i> <i>x</i>

Access the horizontal and vertical cursor position of the window in virtual screen coordinates.

<h2>Joysticks</h2>

<h3>procedure: <code>(joystick-present?

Checks whether a joystick with the given index is connected to the system.

<h3>procedure: <code>(joystick-name

Retrieves the name of the given joystick.

<h3>procedure: <code>(joystick-axes

Retrieves a vector of positions along each of the given joystick's axes.

<h3>procedure: <code>(joystick-buttons

Retrieves a vector of booleans representing the state of each of the given joystick's buttons.

<h2>Events</h2>

<h3>procedure:

Process all pending events.

<h3>procedure:

Wait for at least one events and process it.

<h3>procedure:

Inject an empty event into the queue.

<h3>syntax: <code>(modifier
<h3>syntax: <code>(modifiers <i>symbol</i>

The modifier enumeration is used to indicate keyboard modifiers with the symbols <tt>shift</tt>, <tt>control</tt>, <tt>alt</tt>, <tt>super</tt>, <tt>keypad</tt>. The <tt>keypad</tt> modifier only occurs for key input events and indicates that a key on the numeric keypad was used.

<h3>callback: <code>(<i>proc</i> <i>window</i>

Notifies the callback that the user requested to close the window and the <tt>window-should-close?</tt> flag has been set.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'position <i>x</i>

Notifies the callback that the window's position on the screen has changed.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'size <i>x</i>

Notifies the callback that the window's size on the screen has changed.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'framebuffer-size <i>x</i>

Notifies the callback that the size of the window's framebuffer has changed.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'iconified

Notifies the callback that the window has been iconified or restored.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'focused

Notifies the callback that the window has gained or lost input focus.

<h3>callback: <code>(<i>proc</i> <i>window</i>

Notifies the callback that the window needs to be redrawn.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'key <i>key</i> <i>code</i> <i>action</i>

Notifies the callback of keyboard input.

The key is either a character, one of the symbols <tt>escape</tt>, <tt>enter</tt>, <tt>tab</tt>, <tt>backspace</tt>, <tt>insert</tt>, <tt>delete</tt>, <tt>right</tt>, <tt>left</tt>, <tt>down</tt>, <tt>up</tt>, <tt>page-up</tt>, <tt>page-down</tt>, <tt>home</tt>, <tt>end</tt>, <tt>caps-lock</tt>, <tt>scroll-lock</tt>, <tt>num-lock</tt>, <tt>print-screen</tt>, <tt>pause</tt>, <tt>f1</tt> through <tt>f25</tt>, <tt>left-shift</tt>, <tt>left-control</tt>, <tt>left-alt</tt>, <tt>left-super</tt>, <tt>right-shift</tt>, <tt>right-control</tt>, <tt>right-alt</tt>, <tt>right-super</tt>, <tt>menu</tt> or <tt>#f</tt> if the key cannot be identified.

The code is a platform-specific scan code for the key.

The action is either <tt>press</tt>, <tt>repeat</tt> or <tt>#f</tt> if the key was released.

The modifiers are an enumeration set as described above.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'char

Notifies the callback that the user has input a character.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'cursor-position <i>x</i>

Notifies the callback that the cursor has moved in the window.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'cursor-inside

Notifies the callback that the cursor has moved into or out of the window.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'mouse-button <i>button</i> <i>action</i>

Notifies the callback that a mouse was pushed or released in the window. The button is specified as an integer index, the action is <tt>#t</tt> for a pushed button or <tt>#f</tt> for a released button and the modifiers are an enumeration set as described above.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'scroll <i>x</i>

Notifies the callback that the window has been scrolled.

<h3>callback: <code>(<i>proc</i> <i>window</i> 'drop

Notifies the callback that files have been dropped on the window. The files are passed as a list of absolute paths.