chickadee » glfw3

glfw3

Description

Bindings to the GLFW OpenGL window and event management library, version 3.X. Version 3 of GLFW is not backwards compatible with previous major versions of GLFW.

The CHICKEN 5 port of this egg still needs some work and testing regarding OS X and Windows support.

When using with OpenGL ES, make sure GLFW is appropriately compiled (e.g.: cmake -DGLFW_USE_EGL=ON -DGLFW_CLIENT_LIBRARY=glesv2 -DBUILD_SHARED_LIBS=ON).

When installing GLFW on OS X through Homebrew, an extra step is needed. Homebrew renames the library’s from the default. You can fix this by creating a link that points to the library that gets installed. E.g. sudo ln -s <homebrew-lib-dir>/libglfw3.dylib /usr/local/lib/libglfw.dylib

Requirements

Documentation

The glfw3 egg provides two different modules: glfw3-bindings and glfw3. For almost all purposes, only glfw3 should be needed.

glfw3-bindings provides direct bindings to GLFW generated by bind. Names have been converted from camelCase to hyphenated, with GLFW prefixes removed (e.g. glfwGetTimerValue becomes get-timer-value). Constants are lower-cased and surrounded by +s (e.g. GLFW_ALPHA_BITS becomes +alpha-bits+).

glfw3 is the high-level interface that should be used in most cases. At the moment it is largely re-exporting glfw3-bindings, although many of these functions could still use wrappers (patches welcome!). The not-exactly-the-same-as-the-glfw-api functions are described in the section High-level interface.

For information regarding the GLFW API, see the official GLFW documentation.

High-level interface

initprocedure

Initializes glfw. Not needed when using with-window.

windowparameter

Contains the window associated with the current context.

make-context-current WINDOWprocedure

Performs glfwMakeContextCurrent while setting the above window parameter to the new value.

make-window WIDTH HEIGHT NAME #!key (fullscreen? #f) (swap-interval 1) resizable visible decorated red-bits green-bits blue-bits alpha-bits depth-bits stencil-bits accum-red-bits accum-green-bits accum-blue-bits accum-alpha-bits aux-buffers samples refresh-rate sterio srgb-capable client-api context-version-major context-version-minor context-robustness opengl-forward-compat opengl-debug-context opengl-profileprocedure

Create a window with title string NAME and dimensions WIDTH by HEIGHT. The keys correspond to the available GLFW window hints. resizable, visible, decorated, stereo, srgb-capable, opengl-forward-compat, opengl-debug-context accept boolean arguments, while all other accept either an integer or an appropriate GLFW constant as per the documentation.

Sets the current context to the window that was created. The swap interval of the window is set to the value of theswap-interval key. Finally, this initializes all of the window-specific callbacks.

When using with OS X, make sure you ask for the right context. Only OS X 10.7+ support core contexts, and only limited contexts are supported. See the GLFW FAQ. For instance:

(make-window WIDTH HEIGHT NAME
             context-version-major: 3
             context-version-minor: 2
             opengl-forward-compat: #t
             opengl-profile: +opengl-core-profile+)

(with-window (WIDTH HEIGHT NAME . KEYS) BODY ...)syntax

Initializes GLFW, creates a window as per make-window, and runs BODY before cleaning up.

Callbacks

glfw3 provides parameters which contain the functions that are called from GLFW callbacks. The GLFW callbacks are initialized to call these parameters when init and make-window or with-window are used, but they can be changed with the callback setter functions.

window-position-callbackparameter

Called when a window is moved. Expects a function with the signature (lambda (WINDOW X Y) ...). WINDOW is the window that was moved. X and Y are the coordinates of the upper-left corner of the window.

window-size-callbackparameter

Called when a window is resized. Expects a function with the signature (lambda (WINDOW W H) ...). WINDOW is the window that was resized. W and H are the new dimensions of the window.

window-close-callbackparameter

Called when a window is closed. Expects a function with the signature (lambda (WINDOW) ...). WINDOW is the window that was closed.

window-refresh-callbackparameter

Called when a window’s content is damaged and needs to be refreshed. Expects a function with the signature (lambda (WINDOW) ...). WINDOW is the window that needs refreshing.

window-focus-callbackparameter

Called when a window comes into or goes out of focus. Expects a function with the signature (lambda (WINDOW FOCUSED?) ...). WINDOW is the affected window, while FOCUSED? is true when the window has been focused and false otherwise.

window-iconify-callbackparameter

Called when a window is iconified or restored. Expects a function with the signature (lambda (WINDOW ICONIFIED?) ...). WINDOW is the affected window, while ICONIFIED? is true when the window has been iconified and false otherwise.

framebuffer-size-callbackparameter

Called when a framebuffer is resized. Expects a function with the signature (lambda (WINDOW W H) ...). WINDOW is the window whose framebuffer was resized. W and H are the new dimensions, in pixels, of the framebuffer.

mouse-button-callbackparameter

Called when a mouse button is pressed or released. Expects a function with the signature (lambda (WINDOW BUTTON ACTION MODS) ...). WINDOW is the window where the button was pressed, BUTTON is the name of the mouse button (one of +mouse-button-1+ through +mouse-button-8+, +mouse-button-last+, +mouse-button-left+, +mouse-button-right+, +mouse-button-middle+), ACTION is one of +press+ or +release+, and MODS is a bit field describing the modifier keys that were held down (any of +mod-shift+, +mod-control+, +mod-alt+, or +mod-super+).

cursor-enter-callbackparameter

Called when a cursor enters or leaves a window. Expects a function with the signature (lambda (WINDOW ENTERED?) ...). WINDOW is the affected window, and ENTERED? is true when the window was entered and false otherwise.

cursor-position-callbackparameter

Called when a cursor moves. Expects a function with the signature (lambda (WINDOW X Y) ...). WINDOW is the affected window. X and Y is the new coordinates of the cursor.

scroll-callbackparameter

Called when a scroll occurs. Expects a function with the signature (lambda (WINDOW X Y) ...). WINDOW is the affected window. X and Y are the scroll offsets.

key-callbackparameter

Called when a key is pressed or released. Expects a function with the signature (lambda (WINDOW KEY SCANCODE ACTION MODS) ...). WINDOW is the window where the button was pressed, KEY is the name of the key, SCANCODE is the system-specific scancode of the key, ACTION is one of +press+, +release+ or +repeat+, and MODS is a bit field describing the modifier keys that were held down (any of +mod-shift+, +mod-control+, +mod-alt+, or +mod-super+).

char-callbackparameter

Called when character is entered. Expects a function with the signature (lambda (WINDOW CHAR) ...). WINDOW is the affected window, and CHAR is the unicode code point of the character.

char-mods-callbackparameter

Called when character is entered, but also includes modifiers that were active when the character was entered. Expects a function with the signature (lambda (WINDOW CHAR MODS) ...). WINDOW is the affected window, and CHAR is the unicode code point of the character, MODS is the bitfield of the modifiers that were active.

monitor-callbackparameter

Called when a monitor is connected or disconnected. Expects a function with the signature (lambda (MONITOR EVENT) ...). MONITOR is a pointer to the affected monitor, EVENT is either +connected+ or +disconnected+.

joystick-callbackparameter

Called when a joystick is plugged-in or plugged-out. Expects a function with the signature (lambda (JOYSTICK EVENT) ...). JOYSTICK is an integer representing the joystick, EVENT is either +connected+ or +disconnected+.

set-window-position-callback! #!optional WINDOW CALLBACKprocedure
set-window-size-callback! #!optional WINDOW CALLBACKprocedure
set-window-close-callback! #!optional WINDOW CALLBACKprocedure
set-window-refresh-callback! #!optional WINDOW CALLBACKprocedure
set-window-focus-callback! #!optional WINDOW CALLBACKprocedure
set-window-iconify-callback! #!optional WINDOW CALLBACKprocedure
set-framebuffer-size-callback! #!optional WINDOW CALLBACKprocedure
set-mouse-button-callback! #!optional WINDOW CALLBACKprocedure
set-cursor-enter-callback! #!optional WINDOW CALLBACKprocedure
set-cursor-position-callback! #!optional WINDOW CALLBACKprocedure
set-scroll-callback! #!optional WINDOW CALLBACKprocedure
set-key-callback! #!optional WINDOW CALLBACKprocedure
set-char-callback! #!optional WINDOW CALLBACKprocedure
set-char-mods-callback! #!optional WINDOW CALLBACKprocedure
set-monitor-callback! #!optional CALLBACKprocedure
set-joystick-callback! #!optional CALLBACKprocedure

Set the callback functions associated with WINDOW. Used when the callback parameters are not desired. WINDOW defaults to window. CALLBACK defaults to an external function that calls the corresponding callback parameter.

Modified functions

The following functions take a different number of arguments than their GLFW counterparts. This is because the original function accepted values passed by reference for modification.

get-versionprocedure

Returns three values: the major version , minor version , and revision number of the GLFW library.

get-monitorsprocedure

Returns two values: A pointer to an array of GLFWmonitor references, and the number of values in the array.

get-monitor-position MONITORprocedure

Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the MONITOR’s viewport on the virtual screen.

get-monitor-physical-size MONITORprocedure

Returns two values: the physical width and height, in millimetres, of the MONITOR.

get-video-modes MONITORprocedure

Returns two values: A pointer to an array of video modes, and the number of values in the array.

get-window-position WINDOWprocedure

Returns two values: the x and y position, in screen coordinates, of the upper-left corner of the WINDOW.

set-window-position WINDOW X Yprocedure

Set the position of the upper-left corner of the WINDOW.

get-window-size WINDOWprocedure

Returns two values: the width and height, in screen coordinates, of the WINDOW.

get-framebuffer-size WINDOWprocedure

Returns two values: the width and height, in pixels, of the framebuffer of WINDOW.

get-cursor-position WINDOWprocedure

Returns two values: the x and y position of the cursor, relative to the upper-left edge of the client area of the WINDOW.

set-cursor-position WINDOW X Yprocedure

Set the position of the cursor, relative to the upper-left edge of the client area of the WINDOW.

get-joystick-axes JOYSTICKprocedure

Returns two values: a pointer to an array of floats representing the values of all axes of the specified joystick, and the number of values in the array. You can use pointer-f32-ref to get the axes coordinates.

get-joystick-buttons JOYSTICKprocedure

Returns two values: a pointer to an array of bytes representing the state of all buttons on the specified joystick, and the number of values in the array. You can use pointer-u8-ref to get the button states.

Example

 
(import (prefix glfw3 glfw:))

(glfw:key-callback (lambda (window key scancode action mods)
                     (cond
                      [(and (eq? key glfw:+key-escape+) (eq? action glfw:+press+))
                       (glfw:set-window-should-close window #t)])))

(glfw:with-window (640 480 "Example" resizable: #f)
    (let loop ()
      (glfw:swap-buffers (glfw:window))
      (glfw:poll-events)
      (unless (glfw:window-should-close (glfw:window))
        (loop))))

Version history

Version 0.7.1

25 June 2019

Version 0.7.0

15 March 2019

Version 0.6.1

20 November 2014

Version 0.5.2

20 October 2014

Version 0.5.1

11 June 2014

Version 0.5.0

10 June 2014

Version 0.4.1

23 May 2014

Version 0.4.0

22 May 2014

Version 0.3.0

Version 0.2.0

Version 0.1.0

Source repository

Source available here.

Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com

Authors

Alex Charlton Adrien (Kooda) Ramos

Licence

BSD

Contents »