MoonGLFW Reference Manual

Preface

This is the reference manual of MoonGLFW, which is a Lua binding library for GLFW. ^[1]

It is assumed that the reader is familiar with both GLFW and the Lua programming language.

For convenience of reference, this document contains external (deep) links to the Lua Reference Manual and the GLFW documentation.

Getting and installing

For installation intructions, refer to the README file in the MoonGLFW official repository on GitHub.

Module organization

The MoonGLFW module is loaded using Lua’s require() and returns a table containing the functions it provides (as usual with Lua modules). This manual assumes that such table is named glfw, i.e. that it is loaded with:

 glfw = require("moonglfw")

but nothing forbids the use of a different name.

Examples

A few examples can be found in the examples/ directory of the release package.

License

MoonGLFW is released under the MIT/X11 license (same as Lua, and with the same only requirement to give proper credits to the original author). The copyright notice is in the LICENSE file in the base directory of the official repository on GitHub.

Bindings

The structure of this section purposedly replicates the structure of the GLFW Reference documentation.

All the functions listed in the following sections are members of the glfw table.

Functions tagged with NONGLFW are MoonGLFW additions that do not map directly to GLFW functions.

Context

Rfr: Context.

make_context_current(window)

window = get_context_current(window)
Returns nil if there is no current window.

swap_interval(interval)

boolean = extension_supported(extension)
extension: a string.

Initialization, version and errors

Rfr: Initialization, version and errors.

MoonGLFW automatically calls glfwInit( ) when it is loaded, and glfwTerminate( ) at exit.

init_hint(hint, value)
init( )
Use these functions only if you need to set some init hints, which are to be set before initialization of GLFW. If GLFW has already been initialized, calling init_hint( ) automatically terminates it. After having set the desired hints, call init( ) to finilize the initialization.
The glfw table contains the following version fields:
- _VERSION: a string describing the MoonGLFW version, and
- _GLFW_VERSION: a string describing the GLFW version.

major, minor, rev = get_version( )

string= get_version_string( )

platform = get_platform( )
boolean = platform_supported(platform)
'platform': 'null' | 'win32' | 'cocoa' | 'wayland' | 'x11'.

set_error_callback([func])
The func callback is executed as func(ec, descr) where ec (an integer) is the error code and descr (a string) is the description of the occurred error.
If func is nil, unregisters the current error callback (if any).

Input

Rfr: Input.

set_input_mode(window, mode, value)
value = get_input_mode(window, mode)
mode: 'cursor' | 'sticky keys' | 'sticky mouse buttons' | 'lock key mods' | 'raw mouse motion'.
value: one of the following, depending on mode:
- if mode is 'cursor': value = 'normal' | 'hidden' | 'disabled' | 'captured'.
- otherwise: value = boolean.

boolean = raw_mouse_motion_supported( )

Keyboard

state = get_key(window, key)
state: 'press' | 'release'.

name = get_key_name(key | scancode)
See set_key_callback( ).

scancode = get_key_scancode(key)

Mouse/Cursor

state = get_mouse_button(window, button)
button: 'left' | 'middle' | 'right' | 'button 4' | .. | 'button 8'.
state: 'press' | 'release'.

set_cursor_pos(window, xpos, ypos)
xpos, ypos = get_cursor_pos(window)
xpos, ypos: float.

cursor = create_cursor(width, height, pixels, xhot, yhot)
cursor = create_cursor(shape)
width, height (integers) and pixels (binary string) specify the image.
shape: 'arrow' | 'ibeam' | 'crosshair' | 'hand' | 'hresize' | 'vresize' | 'resize nwse' | 'resize nesw' | 'resize all' | 'not allowed'.
Both functions return a cursor handle to the newly created cursor.

destroy_cursor(cursor)

set_cursor(window, cursor)

Joystick/Gamepad

boolean = joystick_present(jid)
jid: integer (1..16).

xpos, … = get_joystick_axes(jid)

state₁, … = get_joystick_buttons(jid)
state: 'press' | 'release'.
Note: Joystick hats are included if GLFW version < 3.3.0 is being used (see: GLFW_JOYSTICK_HAT_BUTTONS).

hats₁, … = get_joystick_hats(jid)

name = get_joystick_name(jid)

guid = get_joystick_guid(jid)
guid: string or nil.

boolean = joystick_is_gamepad(jid)

name = get_gamepad_name(jid)
Returns nil on error.

buttons, axes = get_gamepad_state(jid)
Returns nil on error.

boolean = update_gamepad_mappings(string)

Clipboard

set_clipboard_string(window, string)
string = get_clipboard_string(window)

Time

set_time(time)
time = get_time( )

hz = get_timer_frequency( )
tics = get_timer_value( )
seconds = get_timer_seconds( ) NONGLFW
seconds = tics * 1/hz.

The following NONGLFW time utilities are added for consistency with the time utilities that can be found in other libraries of the MoonLibs collection.

t = now( ) NONGLFW
Returns the current time in seconds (a Lua number).
This is implemented with monotonic clock_gettime(3), if available, or with gettimeofday(3) otherwise.

dt = since(t) NONGLFW
Returns the time in seconds (a Lua number) elapsed since the time t, previously obtained with the now( ) function.

sleep(seconds) NONGLFW
Sleeps for seconds.

Input callbacks

Rfr: Input.

All the following functions, when invoked with func=nil, unregister the corresponding current callback.

set_key_callback(window, [func])
The func callback is executed as func(window, key, scancode, action, shift, control, alt, super), where:
key: see key.
action: 'press' | 'release' | 'repeat'.
shift, control, alt, super: boolean (modifiers).

set_char_callback(window, [func])
The func callback is executed as func(window, codepoint).

set_char_mods_callback(window, [func]) DEPRECATED
The func callback is executed as func(window, codepoint, shift, control, alt, super), where:
shift, control, alt, super: boolean (modifiers).

set_mouse_button_callback(window, [func])
The func callback is executed as func(window, button, action, shift, control, alt, super), where:
button: 'left' | 'right' | 'middle' | 'button 4' | .. | 'button 8'.
action: 'press' | 'release'.
shift, control, alt, super: boolean (modifiers).

set_cursor_pos_callback(window, [func])
The func callback is executed as func(window, xpos, ypos), where xpos and ypos are floats.

set_cursor_enter_callback(window, [func])
The func callback is executed as func(window, entered), where entered is a boolean.

set_scroll_callback(window, [func])
The func callback is executed as func(window, xoffset, yoffset), where xoffset and yoffset are floats.

set_drop_callback(window, [func])
The func callback is executed as func(window, path, …), where path is a string (and any subsequent argument too).

set_joystick_callback([func])
The func callback is executed as func(jid, event), where:
jid: integer (1..16),
event: 'connected' | 'disconnected'.

Monitor

Rfr: Monitor.

monitor₁, monitor₂, … = get_monitors( )

monitor = get_primary_monitor( )

xpos, ypos = get_monitor_pos(monitor)

widthmm, heightmm = get_monitor_physical_size(monitor)

name = get_monitor_name(monitor)

videomode = get_video_mode(monitor)
videomode₁, videomode₂, … = get_video_modes(monitor)

set_gamma(monitor, gamma)

set_gamma_ramp(monitor, red, green, blue)
red, green, blue = get_gamma_ramp(monitor)
red, green and blue: equally sized arrays (tables) of integers.

xpos, ypos, width, height = get_monitor_workarea(monitor)

xscale, yscale = get_monitor_content_scale(monitor)

Monitor callbacks

Rfr: Monitor.

set_monitor_callback(monitor, [func])
The func callback is executed as func(monitor, event), where event (a string) may be 'connected' or 'disconnected'.
If func=nil, unregisters the current callback (if any).

Native access

Rfr: Native access.

string = get_win32_adapter(monitor)
string = get_win32_monitor(_monitor)
lightuserdata = get_win32_window(window)
lightuserdata = get_wgl_context(window)
lightuserdata = get_x11_display( )
integer = get_x11_adapter(monitor)
integer = get_x11_monitor(monitor)
integer = get_x11_window(window)
string = get_x11_selection_string( )
set_x11_selection_string(string )
lightuserdata = get_glx_context(window)
integer = get_glx_window(window)
lightuserdata = get_wayland_display( )
lightuserdata = get_wayland_monitor(monitor)
lightuserdata = get_wayland_window(window)
lightuserdata = get_mir_display( ) DEPRECATED
integer = get_mir_monitor(monitor)
lightuserdata = get_mir_window(window)
lightuserdata = get_egl_display( )
lightuserdata = get_egl_context(window)
lightuserdata = get_egl_surface(window)
lightuserdata = get_osmesa_context(window)
width, height, format, buffer = get_osmesa_color_buffer(window)
width, height, bytespervalue, buffer = get_osmesa_depth_buffer(window)
width, height, format, bytespervalue: integer,
buffer: lightuserdata.
context, system = get_context(window) NONGLFW
Returns the GL context (lightuserdata) associated with window, followed by a string denoting the system ('wgl', 'glx', 'egl', or 'osmesa').
Returns nil if the GL context can not be retrieved.
(This function can be used instead of get_xxx_context( ) when xxx is unknown to the application).

Window

Rfr: Window.

default_window_hints( )

window_hint(target, hint)

version_hint(major, minor, profile) NONGLFW
Combined window_hint for the following targets: 'context version major', 'context version minor', and 'opengl version'.

window = create_window(width, height, [title], [monitor], [sharewindow])
Returns a window handle to the newly created window.

destroy_window(window)

focus_window(window)

request_window_attention(window)

set_window_should_close(window, boolean)
boolean = window_should_close(window)

set_window_title(window, title)
title = get_window_title(window)

set_window_icon(window, width, height, pixels, [width₂, height₂, pixels₂, …])
width, height (integers), and pixels (binary string) specify the image.
Other images (up to 32 total) can be added in the optional part in the same way.

set_window_monitor(window, [monitor], xpos, ypos, width, height, [refresh_rate])

set_window_pos(window, xpos, ypos)
xpos, ypos = get_window_pos(window)

set_window_size(window, width, height)
width, height = get_window_size(window)

set_window_aspect_ratio(window, numer, denom)
A nil value for numer or denom means "don't care".

set_window_size_limits(window, minwidth, minheight, maxwidth, maxheight)
A nil value for minwidth, minheight, maxwidth, or maxheight means "don't care".

width, height = get_framebuffer_size(window)

left, top, right, bottom = get_window_frame_size(window)

iconify_window(window)
restore_window(window)
maximize_window(window)

show_window(window)
hide_window(window)

monitor = get_window_monitor(window)

value = get_window_attrib(window, attrib)
set_window_attrib(window, attrib, value)
attrib, value: see target and hint for the window_hint( ) function.

xscale, yscale = get_window_content_scale(window)

set_window_opacity_(window, opacity)
opacity = get_window_opacity_(window)

poll_events( )

wait_events( )

wait_events_timeout(seconds)

post_empty_event( )

swap_buffers(window)

Window callbacks