Lua logo

Preface

This is the reference manual of MoonGLUT, which is a Lua binding library for FreeGLUT. [1]

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

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

Getting and installing

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

Module organization

The MoonGLUT 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 glut, i.e. that it is loaded with:

 glut = require("moonglut")

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

MoonGLUT 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

Initialization Functions

References: FreeGLUT, GLUT.

  • arg = init([arg])
    Binding to glutInit.
    The optional arg argument must be a sequence of strings (typically the table of arguments passed to the Lua script at the command line). Returns a copy of the same table stripped from any option recognized by FreeGLUT.

  • major, minor, profile, debug = init_context(major, minor, profile [, debug])
    Binding to glutInitContextFlags, glutInitContextProfile, and glutInitContextVersion.
    The major and minor parameters are the context version numbers. The profile parameter (a string) may be one amongst: 'core', 'compatible' and 'forward compatible' (corresponding to, respectively: 'all features of the current release', 'all features ever', 'only non deprecated features'). If the debug parameter (a boolean) is true, then the debug flag is set. With no arguments, this function only returns the current values.

  • x, y = init_window_position([x, y])
    Binding to glutInitWindowPosition.
    With no arguments, only returns the current values.

  • width, height = init_window_size([width, height])
    Binding to glutInitWindowSize.
    With no arguments, only returns the current values.

  • opt, …​ = init_display_mode([opt, …​])
    Binding to glutInitDisplayMode. Accepts a list of options (strings).
    Valid options are: 'rgb', 'rgba', 'index', 'single', 'double', 'accum', 'alpha', 'depth', 'stencil', 'multisample', 'stereo' and 'luminance'.
    With no arguments, only returns the current options.

  • init_error_func([func])
    Binding to glutInitErrorFunc.
    The func callback is executed as func(message) where message is a string.

  • init_warning_func([func])
    Binding to glutInitWarningFunc.
    The func callback is executed as func(message) where message is a string.

Event Processing Functions

References: FreeGLUT, GLUT.

  • main_loop( )
    Binding to glutMainLoop.

  • main_loop_event( )
    Binding to glutMainLoopEvent.

  • leave_main_loop( )
    Binding to glutLeaveMainLoop.

  • exit( )
    Binding to glutExit.

Window Functions

References: FreeGLUT, GLUT.

  • window_id = create_window(title)
    Binding to glutCreateWindow.

  • window_id = create_sub_window(parent_id, x, y, width, height)
    Binding to glutCreateSubwindow.

  • destroy_window(window_id)
    Binding to glutDestroyWindow.

  • set_window(window_id)
    Binding to glutSetWindow.

  • window_id = get_window( )
    Binding to glutGetWindow.

  • set_window_title(title)
    Binding to glutSetWindowTitle.

  • set_icon_title(title)
    Binding to glutSetIconTitle.

  • reshape_window(width, height)
    Binding to glutReshapeWindow.

  • position_window(x, y)
    Binding to glutPositionWindow.

  • show_window( )
    Binding to glutShowWindow.

  • hide_window( )
    Binding to glutHideWindow.

  • iconify_window( )
    Binding to glutIconifyWindow.

  • push_window( )
    Binding to glutPushWindow.

  • pop_window( )
    Binding to glutPopWindow.

  • boolean = full_screen(boolean)
    Binding to glutFullScreen and to glutLeaveFullScreen.

  • full_screen_toggle()
    Binding to glutFullScreenToggle.

Display Functions

References: FreeGLUT, GLUT.

  • post_redisplay( )
    Binding to glutPostRedisplay.

  • post_window_redisplay(window_id)
    Binding to glutPostWindowRedisplay.

  • swap_buffers( )
    Binding to glutSwapBuffers.

Mouse Cursor Functions

References: FreeGLUT, GLUT.

  • cursor = cursor([cursor])
    Binding to glutSetCursor.
    The optional cursor argument (a string) must be one of the following: 'right arrow', 'left arrow', 'info', 'destroy', 'help', 'cycle', 'spray', 'wait', 'text', 'crosshair', 'up down', 'left right', 'top side', 'bottom side', 'left side', 'right side', 'top left corner', 'top right corner', 'bottom right corner', 'bottom left corner', 'inherit', 'none', or 'full crosshair'.
    With no arguments, only returns the current cursor.

  • warp_pointer(x, y)
    Binding to glutWarpPointer.

Overlay Functions

References: FreeGLUT, GLUT.

Not supported.

Menu Functions

References: FreeGLUT, GLUT.

  • menu_id = create_menu(func)
    Binding to glutCreateMenu.
    The func callback is executed as func(window_id, menu_id, value).

  • destroy_menu(menu_id)
    Binding to glutDestroyMenu.

  • menu_id = get_menu( )
    Binding to glutGetMenu.

  • set_menu(menu_id)
    Binding to glutSetMenu.

  • add_menu_entry(label, value)
    Binding to glutAddMenuEntry.

  • add_sub_menu(label, submenu)
    Binding to glutAddSubMenu.

  • change_to_menu_entry(item, label, value)
    Binding to glutChangeToMenuEntry.

  • change_to_sub_menu(item, label, value)
    Binding to glutChangeToSubMenu.

  • remove_menu_item(item)
    Binding to glutRemoveMenuItem.

  • attach_menu(button)
    detach_menu(button)
    Bindings to glutAttachMenu and to glutDetachMenu, respectively.
    The button argument (a string) must be one amongst 'left', 'middle', and 'right'.

  • menu_destroy_func(func)
    Binding to glutMenuDestroyFunc.
    The func callback is executed as func(window_id, menu_id).

Global Callback Registration Functions

References: FreeGLUT, GLUT.

  • timer_func(msec, _func, arg)
    Binding to glutTimerFunc.
    The func callback is executed as func(arg).

  • idle_func(func)
    Binding to glutIdleFunc.
    The func callback is executed as func(window_id, menu_id).

  • menu_status_func([func])
    Binding to glutMenuStatusFunc.
    The func callback is executed as func(status, x, y), where status is a string that may be either 'in use' or 'not in use'.

Window-Specific Callback Registration Functions

References: FreeGLUT, GLUT.

Registration functions can be invoked with no arguments in order to unregister the current callback (if any).

All the window-specific callbacks receive the identifier of the current window as first parameter (window_id).

For callbacks that receive x and y parameters, these give the current position of the mouse cursor.

  • display_func([func])
    Binding to glutDisplayFunc.
    The func callback is executed as func(window_id).

  • reshape_func([func])
    Binding to glutReshapeFunc.
    The func callback is executed as func(window_id, width, height).

  • close_func([func])
    Binding to glutCloseFunc.
    The func callback is executed as func(window_id).

  • keyboard_func([func])
    keyboard_up_func([func])
    Bindings to glutKeyboardFunc and to glutKeyboardUpFunc.
    The func callback is executed as func(window_id, key, x, y, code).
    The key parameter (a string) is the pressed character if its ASCII code is between 33 and 126 (letters, numbers etc), otherwise it is one amongst the following: 'nul' (0), 'soh' (1), 'stx' (2), 'etx' (3), 'eot' (4), 'enq' (5), 'ack' (6), 'bel' (7), 'bs' (8), 'ht' (9), 'nl' (10), 'vt' (11), 'ff' (12), 'cr' (13), 'so' (14), 'si' (15), 'dle' (16), 'dc1' (17), 'dc2' (18), 'dc3' (19), 'dc4' (20), 'nak' (21), 'syn' (22), 'etb' (23), 'can' (24), 'em' (25), 'sub' (26), 'esc' (27), 'fs' (28), 'gs' (29), 'rs' (30), 'us' (31), 'space' (32), and 'del' (127).
    For codes greater than 127, string = '\<code>'.
    The code parameter is the corresponding ASCII code.

  • special_func([func])
    special_up_func([func])
    Binding to glutSpecialFunc and to glutSpecialUpFunc.
    The func callback is executed as func(window_id, key, x, y, code).
    The key parameter (a string) is one amongst: 'f1' …​ 'f12', 'left', 'right', 'up', 'down', 'page-up', 'page-down', 'home', 'end', 'ins', 'num-lock', '_begin', 'del', 'shift-l', 'shift-r', 'ctrl-l', 'ctrl-r', 'alt-l' and 'alt-r'.
    The code parameter is the corresponding GLUT_KEY_XXX code.

  • motion_func([func])
    Binding to glutMotionFunc.
    The func callback is executed as func(window_id, x, y).

  • passive_motion_func([func])
    Binding to glutPassiveMotionFunc.
    The func callback is executed as func(window_id, x, y).

  • mouse_func([func])
    Binding to glutMouseFunc.
    The func callback is executed as func(window_id, button, state, x, y).
    The button parameter (a string) is one amongst 'left', 'middle' and 'right'.
    The state parameter (also a string) may be 'up' or 'down'.

  • entry_func([func])
    Binding to glutEntryFunc.
    The func callback is executed as func(window_id, _state).
    The _state     parameter (a string) may be 'in' (entered) or 'out' (left).

  • window_status_func([func])
    Binding to glutWindowStatusFunc.
    The func callback is executed as func(window_id, _state).
    The _state     parameter (a string) is one amongst: 'hidden', 'fully retained', 'partially retained' or 'fully covered'.

State Setting and Retrieval Functions

References: FreeGLUT, GLUT.

  • boolean = init_state( )
    [small]#Binding to glutGet(GLUT_INIT_STATE). #

  • major, minor, micro = version( )
    [small]#Binding to glutGet(GLUT_VERSION). #

  • action = action_on_window_close([action])
    Binding to glutSetOption(GLUT_ACTION_ON_WINDOW_CLOSE).
    The action argument (a string) must be one amongst 'exit', 'return', and 'continue'.

  • boolean = use_current_context([boolean])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_RENDERING_CONTEXT.

  • nsamples = multisample([nsamples])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_MULTISAMPLE.

  • nbuffers = aux_buffers([nbuffers])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_AUX.

  • width, height, width_mm, height_mm = screen( )
    Binding to glutGet(what) where what = GLUT_SCREEN_WIDTH, GLUT_SCREEN_HEIGHT, GLUT_SCREEN_WIDTH_MM and GLUT_SCREEN_HEIGHT_MM.

  • boolean = skip_stale_motion_events([boolean])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_SKIP_STALE_MOTION_EVENTS.

  • boolean = stroke_font_draw_join_dots([boolean])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_STROKE_FONT_DRAW_JOIN_DOTS.

  • boolean = geometry_visualize_normals([boolean])
    Binding to glutGet(what) and to glutSetOption(what) where what = GLUT_GEOMETRY_VISUALIZE_NORMALS.

Other bindings to glutGet(what) and to glutSetOption(what):
- what = GLUT_INIT_WINDOW_X: see glut.init_window_position
- what = GLUT_INIT_WINDOW_Y: see glut.init_window_position
- what = GLUT_INIT_WINDOW_WIDTH: see glut.init_window_size
- what = GLUT_INIT_WINDOW_HEIGHT: see glut.init_window_size
- what = GLUT_INIT_DISPLAY_MODE: see glut.init_display_mode
- what = GLUT_WINDOW_CURSOR: see glut.cursor
- what = GLUT_FULL_SCREEN: see glut.full_screen

Font Rendering Functions

References: FreeGLUT, GLUT.

In the functions that follow, the font argument is a string amongst:
Bitmap fonts: 'bitmap 9 by 15', 'bitmap 8 by 13', 'bitmap times roman 10', 'bitmap times roman 24', 'bitmap helvetica 10', 'bitmap helvetica 12' and 'bitmap helvetica 18'.
Stroke fonts: 'stroke roman' and 'stroke mono roman'.

  • bitmap_character(font, char)
    Binding to glutBitmapCharacter.

  • bitmap_string(font, string)
    Binding to glutBitmapString.

  • width = bitmap_width(font, char)
    Binding to glutBitmapWidth.

  • length = bitmap_length(font, string)
    Binding to glutBitmapLength.

  • height = bitmap_height(font)
    Binding to glutBitmapHeight.

  • stroke_character(font, char)
    Binding to glutStrokeCharacter.

  • stroke_string(font, string)
    Binding to glutStrokeString.

  • width = stroke_width(font, char)
    Binding to glutStrokeWidth.

  • length = stroke_length(font, string)
    Binding to glutStrokeLength.

  • height = stroke_height(font)
    Binding to glutStrokeHeight.

Geometric Object Rendering Functions

References: FreeGLUT, GLUT.

Not supported.

Game Mode Functions

References: FreeGLUT.

  • game_mode_string(mode)
    Binding to glutGameModeString.

  • window_id = enter_game_mode( )
    Binding to glutEnterGameMode.

  • leave_game_mode( )
    Binding to glutLeaveGameMode.

  • value = game_mode_get([name])
    Binding to glutGameModeGet.
    The parameter name may be a string amongst: 'active', 'possible' and 'display changed' (these return a boolean value) or 'width', 'height', 'pixel depth', and 'refresh rate' (return an integer value).

Video Resize Functions

References: FreeGLUT.

Not supported.

Color Map Functions

References: FreeGLUT, GLUT.

  • red, green, blue = set_color(cell [, red, green, blue])
    Binding to glutSetColor.
    With no color arguments, only returns the current values.

  • red, green, blue = get_color(cell)
    Binding to glutGetColor(actually an alias of glut.set_color).

  • copy_colormap([window_id])
    Binding to glutCopyColormap.

MultiTouch Functions

References: FreeGLUT.

Not supported.

Mobile functions

References: FreeGLUT.

Not supported.

Miscellaneous Functions

References: FreeGLUT.

  • set_key_repeat([option])
    Binding to glutSetKeyRepeat.
    The option argument (a string) must be one amongst 'on', 'off', and 'default'.

  • ignore_key_repeat(boolean)
    Binding to glutIgnoreKeyRepeat.

  • report_errors( )
    Binding to glutReportErrors.

1. This manual is written in AsciiDoc, rendered with AsciiDoctor and a CSS from the AsciiDoctor Stylesheet Factory. The PDF version is produced with AsciiDoctor-Pdf.