/moonlibs

Lua libraries for graphics and audio programming

MoonLibs - Graphics and Audio Lua Libraries

A collection of libraries for graphics, audio, and heterogeneous programming in Lua (>= 5.3), mostly bindings to popular C/C++ libraries.

They currently run on GNU/Linux and (most of them) on Windows with MSYS2/MinGW-w64. A few of them also run on MacOS, thanks to contributions from other developers.

The libraries do not depend on each other, so they can be selectively installed (they must, actually, since this repository is only a collector of links to the repos of the individual libraries).

For bug reports, suggestions, etc., please open an issue in the repo of the relevant library.

Author: Stefano Trettel

Lua logo

  • GPU rendering and computing:
  • Windowing, input handling, GUI:
  • Math and Physics:
    • MoonGLMATH (doc) - graphics math library for MoonGL and MoonVulkan.
    • MoonChipmunk (doc) - bindings to the Chipmunk2D game dynamics library.
    • MoonCCD (doc) - bindings to the libccd collision detection library.
    • MoonODE (doc) - bindings to the ODE (Open Dynamics Engine) 3D physics library.
  • Concurrency, State Machines:
  • Image loading:
    • MoonImage (doc) - STB image based image loading library.
    • MoonSOIL (discontinued) - bindings to the Simple OpenGL Image Library.
  • Model loading:
    • MoonAssimp (doc) - bindings to Assimp (Open Asset Import Library).
  • Text rendering:
  • Audio:
  • Other:

Installation instructions

TLDR - Provided you have already installed the toolchain (GNU/Linux, Windows, MacOS) and the needed dependencies, to install a library of the collection all you have to do is clone it, enter its base directory, compile and install. E.g. for MoonFLTK:

$ git clone https://github.com/stetre/moonfltk
$ cd moonfltk
moonfltk$ make
moonfltk$ make install # or: $ sudo make install

To uninstall it:

moonfltk$ make uninstall # or: $ sudo make uninstall

Installing on GNU/Linux

The following instructions show how to install the libraries on Ubuntu. To install on a GNU/Linux distribution other than Ubuntu, replace apt with the package manager used by the distribution (the names of the packages may also differ).

Install the toolchain and Lua

Install the following packages (if you don't have them already):

$ sudo apt install make
$ sudo apt install binutils
$ sudo apt install gcc
$ sudo apt install git

Install the latest version of Lua:

$ sudo apt install libreadline-dev
$ wget https://www.lua.org/ftp/lua-5.3.4.tar.gz
$ tar -zxpvf lua-5.3.4.tar.gz
$ cd lua-5.3.4
lua-5.3.4$ make linux
lua-5.3.4$ sudo make install
Install a library

The following instructions show how to install MoonFLTK, but the same procedure applies to any other any other library of the collection.

First, install any dependencies needed by the library. MoonFLTK needs FLTK, which you can install by typing:

$ sudo apt install libfltk1.3-dev

Then clone the library (or, if you prefer, download the latest release tarball and decompress, it), enter its base directory, compile, and install:

$ git clone https://github.com/stetre/moonfltk
$ cd moonfltk
moonfltk$ make
moonfltk$ sudo make install

To uninstall the library:

moonfltk$ sudo make uninstall

Installing on Windows

The following instructions show how to install the libraries on Windows with MSYS2/MinGW-w64.

Install MSYS2/MinGW-w64

Download the MSYS2 installer and follow the instructions from the download page.

Install the toolchain and Lua

In the following, we'll assume that you installed MSYS2 in the default location C:\msys32. If not, change the paths below accordingly to your chosen location.

Open a MinGW shell (using the shell launcher C:\msys32\mingw32.exe or mingw64.exe, depending on your architecture), and install the following packages:

$ pacman -S make
$ pacman -S tar
$ pacman -S git
$ pacman -S ${MINGW_PACKAGE_PREFIX}-gcc
$ pacman -S ${MINGW_PACKAGE_PREFIX}-lua

Append one of the following two paths, depending on your architecture, to the PATH environment variable:

  • C:\msys32\mingw32\bin (corresponding to /mingw32/bin under MSYS2, for 32-bit), or
  • C:\msys32\mingw64\bin (corresponding to /mingw64/bin under MSYS2, for 64-bit).

(To do so, right click Computer->Properties->Advanced System Settings->Environment variables, then search for the PATH or Path system variable, edit it, and append a semicolon (;) followed by the path).

Now your environment is ready and you should be able to execute the Lua interpreter from the Windows command prompt, by just typing lua in it (to exit from the interpreter, type os.exit() or Ctrl-C in it).

Install a library

The following instructions show how to install MoonFLTK, but the same procedure applies to any other any other library of the collection, provided it is supported on Windows.

First, open a MinGW shell and from there install any dependencies needed by the library. MoonFLTK needs FLTK, which you can install by typing:

$ pacman -S ${MINGW_PACKAGE_PREFIX}-fltk

Then clone the library (or, if you prefer, download the latest release tarball and decompress, it), enter its base directory, compile, and install:

$ git clone https://github.com/stetre/moonfltk
$ cd moonfltk
moonfltk$ make
moonfltk$ make install

To uninstall the library:

moonfltk$ make uninstall

Installing on MacOS

The following instructions show how to install the libraries on MacOS.

Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install Lua
$ brew install lua@5.3
$ brew install luarocks
Install a library

The following instructions show how to install MoonFLTK, but the same procedure applies to any other any other library of the collection, provided it is supported on MacOS.

First, install any dependencies needed by the library. MoonFLTK needs FLTK, which you can install by typing:

$ brew install fltk

Then clone the library (or, if you prefer, download the latest release tarball and decompress, it), enter its base directory, compile, and install:

$ git clone https://github.com/stetre/moonfltk
$ cd moonfltk
moonfltk$ make
moonfltk$ sudo make install

(If MacOS says that The Git command requires the command line developer tools, click Install and Agree to the License Agrement.)

To uninstall the library:

moonfltk$ sudo make uninstall

Dependencies

The same procedures shown above for MoonFLTK apply to any other library of the collection, and differ only in the dependencies (if any, other than Lua and the C standard libraries) that need to be installed.

The dependencies needed by the different libraries are listed below.

GNU/Linux (Ubuntu):

$ sudo apt install libfltk1.3-dev     # needed only by MoonFLTK
$ sudo apt install libglfw3-dev       # needed only by MoonGLFW
$ sudo apt install freeglut3-dev      # needed only by MoonGLUT
$ sudo apt install libglew-dev        # needed only by MoonGL
$ sudo apt install libassimp-dev      # needed only by MoonAssimp
$ sudo apt install libfreetype6-dev   # needed only by MoonFreeType
$ sudo apt install libsndfile1-dev    # needed only by MoonSndFile
$ sudo apt install libopenal-dev      # needed only by MoonAL
$ sudo apt install chipmunk-dev       # needed only by MoonChipmunk
$ sudo apt install libode-dev         # needed only by MoonODE
$ sudo apt install libjack-jackd2-dev # needed only by LuaJack
$ sudo apt install libccd2-dev        # needed only by MoonCCD
$ sudo apt install libsdl2-dev        # needed only by MoonSDL2
$ sudo apt install libsdl2-image-dev  # needed only by MoonSDL2
$ sudo apt install libsdl2-mixer-dev  # needed only by MoonSDL2
$ sudo apt install libsdl2-ttf-dev    # needed only by MoonSDL2

Windows (MSYS2/MinGW-w64):

$ pacman -S ${MINGW_PACKAGE_PREFIX}-fltk        # needed only by MoonFLTK
$ pacman -S ${MINGW_PACKAGE_PREFIX}-glfw        # needed only by MoonGLFW
$ pacman -S ${MINGW_PACKAGE_PREFIX}-freeglut    # needed only by MoonGLUT
$ pacman -S ${MINGW_PACKAGE_PREFIX}-glew        # needed only by MoonGL
$ pacman -S ${MINGW_PACKAGE_PREFIX}-assimp      # needed only by MoonAssimp
$ pacman -S ${MINGW_PACKAGE_PREFIX}-freetype    # needed only by MoonFreeType
$ pacman -S ${MINGW_PACKAGE_PREFIX}-libsndfile  # needed only by MoonSndFile
$ pacman -S ${MINGW_PACKAGE_PREFIX}-openal      # needed only by MoonAL
$ pacman -S ${MINGW_PACKAGE_PREFIX}-chipmunk    # needed only by MoonChipmunk
$ pacman -S ${MINGW_PACKAGE_PREFIX}-ode         # needed only by MoonODE
$ pacman -S ${MINGW_PACKAGE_PREFIX}-SDL2        # needed only by MoonSDL2
$ pacman -S ${MINGW_PACKAGE_PREFIX}-SDL2_image  # needed only by MoonSDL2
$ pacman -S ${MINGW_PACKAGE_PREFIX}-SDL2_mixer  # needed only by MoonSDL2
$ pacman -S ${MINGW_PACKAGE_PREFIX}-SDL2_ttf    # needed only by MoonSDL2

MacOS:

$ brew install fltk        # needed only by MoonFLTK
$ brew install glfw        # needed only by MoonGLFW
$ brew install glew        # needed only by MoonGL

Examples

Each library comes with a few examples, which are located in the examples/ directory of the source package.

Other examples, typically using more than one library, can be found in the examples/ directory of this repository.

The examples are Lua scripts that can be executed with the standard Lua interpreter.

Running the examples

On GNU/Linux, the examples can be executed from the command line. To run, say, the fltk/valuators.lua example, assuming the MoonFLTK source package is located in /home/ste/moonfltk:

$ cd /home/ste/moonfltk/examples/fltk
fltk$ lua valuators.lua

On Windows, the examples can be executed either in a MinGW shell or from a Windows command prompt.

Let's assume the MoonFLTK source package is located in /home/ste/moonfltk under MSYS2, which corresponds to the C:\msys32\home\ste\moonfltk folder under Windows.

To run, say, the fltk/valuators.lua example in a MinGW shell:

$ cd /home/ste/moonfltk/examples/fltk
fltk$ lua valuators.lua

To run the same example from a Windows command prompt:

C:\> cd \msys32\home\ste\moonfltk\examples\fltk
C:\msys32\home\ste\moonfltk\examples\fltk> lua valuators.lua

Tweaks

Lua version

All libraries currently attempt to detect the version of the installed Lua interpreter. If the attempt fails, they assume Lua 5.3. It is possible to compile/install/uninstall explicitly for a given Lua version using the LUAVER variable. For example, to compile and install for Lua 5.4:

moonfltk$ make LUAVER=5.4
moonfltk$ make LUAVER=5.4 install # or: $ sudo make LUAVER=5.4 install

Install location

By default, the libraries are installed under the /usr/local/ directory hierarchy. This is a fairly standard install directory and it is recommended since the Lua interpreter usually has no problem in locating modules when installed here.

It is possible to install the libraries in a different location by overriding the PREFIX variable (whose default value is /usr/local) and letting Lua know at run time where to find them, by adding the path $PREFIX/share/lua/$LUAVER/?.lua to LUA_PATH and the path $PREFIX/lib/lua/$LUAVER/?.so to LUA_CPATH.

For example, to install MoonFLTK under /tmp/myloc:

moonfltk$ make
moonfltk$ make PREFIX=/tmp/myloc install

(Note that this will create the directory tree structure, if not already existing.)

Then set the Lua paths accordingly before running the applications, e.g.:

moonfltk$ LUA_PATH=/tmp/myloc/share/lua/5.3/?.lua
moonfltk$ LUA_CPATH=/tmp/myloc/lib/lua/5.3/?.so
moonfltk$ cd examples/fltk
fltk$ lua valuators.lua