luaglut version 0.5
Introduction
============
luaglut is a set of libraries providing OpenGL and GLUT bindings for
Lua 5. The bindings are in separate libraries, so you don't have to
load the GLUT bindings if you only need OpenGL. The GLUT bindings
also include some GLU functions. These will be eventually moved to
a separate library. luaglut is currently used actively on Lua 5.0.2
but it also works with Lua 5.1 release candidates. The currently
supported operating systems are Linux, Mac OS X and Microsoft Windows
2000/XP (Mingw required for compilation on Windows).
The design of the libraries is a little bit different from the
alternatives:
gllua (http://www.tecgraf.puc-rio.br/~celes/gllua/) only supports
Lua 3.1 and is not developed any more.
Doris (http://doris.sourceforge.net/) suppots Lua 5.0 but rather
than being a standalone library, it includes Lua 5.0 inside it. It
also provides binding to the GLUI user interface toolkit.
LuaGL (http://luagl.sourceforge.net/) is another binding for Lua
5.0 which also has a limited coverage of OpenGL and GLUT and comes
with its own interpreter.
luaglut, on the other hand, is a set of standalone libraries which
can be loaded by a stock Lua distribution and have a much more
complete coverage of the OpenGL and GLUT APIs. I also try to stick
semantically to the OpenGL and GLUT API as closely as possible.
Also, rather than providing custom solutions for creation of memory
buffers (needed for texture mapping and framebuffer operations)
luaglut accepts lightuserdata when a pointer to a raw memory area
is required. It is up to the programmer (i.e. You) to decide which
mechanism for raw memory access you want to use. The current luaglut
distribution includes a simple example of such a library (memarray)
and one of the demo programs uses it to load and display a texture
from a ppm file.
NOTE: memarray was inspired from the LuaMem library written by
Nodir Temirhodzhaev. While a remarkable piece of work, LuaMem
requires some changes to Lua internals which seem to be unsafe
(details on the lua-l list)
Building Instructions
=====================
luaglut supports both Lua 5.0.2 and Lua 5.1. When being built,
luaglut will use include files from the respective Lua version. For
this reason you cannot use the same library with both Lua versions -
it will only run with the Lua version with which it was compiled. If
you need both, you will need to compile two different libraries and
use the respective one with each Lua version.
On the supported platforms, luaglut is built with the 'make'
command. Before giving instructions about building on a particular
platform, let me mention that there are a number of variables that
you can specify on the make command line in order to customize your
build. (DEFS, LIBS, CFLAGS, LFLAGS, GCC_OPT_SHARED, USE_FREEGLUT,
USE_OPENGLUT, USE_OPENGLEAN). I will give some examples below which
will clarify their use.
First of all, it is assumed that Lua headers are installed in
a standard place (like /usr/include). If not, you will need to
specify their location explicitly. Suppose that the headers are in
../lua-5.1/include, then you should issue the following command:
make DEFS=-I../lua-5.1/include
You can also optimize your build by providing extra flags as in
make CFLAGS="-O2 -march=pentium4"
if your cpu is a pentium4 and you want to the C compiler to optimize
at level O2, for example.
luaglut no longer explicitly links to the lua core libraries. Please
read http://lua-users.org/wiki/BuildingModules for more information.
1. Building on Linux
--------------------
Just unpack and run 'make'. This should generate luagl.so, luaglut.so
and memarray.so.
2. Building on Mac OS X
-----------------------
If you have Mac OS X version 10.3.x or greater, you will need to
issue the following command before compiling:
export MACOSX_DEPLOYMENT_TARGET=10.3
If you have Mac OS X version 10.2.x or less, you will need to
link explicitly to the Lua libraries. If your libraries are in
/usr/local/lib, for example, the following line might work:
make \
GCC_OPT_SHARED=-bundle \
LIBS="-L/usr/local/lib -llua -llualib"
The make process should generate luagl.bundle, luaglut.bundle and
memarray.bundle. Many thanks to Anders F. Björklund for providing
patches for Mac OS X/9 support.
For versions earlier than Mac OS X 10.3, you will need 'dlcompat':
http://www.opendarwin.org/projects/dlcompat/
Lua 5.1 is well supported on Mac OS X. For Lua 5.0.2, you will need
to compile Lua with support for dynamic loading. Here are some
instructions that worked for me:
* Get lua-5.0.2.tar.gz and unpack it
* Apply the following patch:
http://www.algonet.se/~afb/lua/lua-5.0.2-darwin.patch
* Don't forget to uncomment the lines for dynamic loading in config
* Issuing the following commands works for me:
make
make dylib
make dylibbin
make install
make dylibinstall
3. Building on Mac OS 9 / X (Carbon) / CodeWarrior
--------------------------------------------------
You can download Lua for Mac OS 9/X (Carbon) from:
http://www.algonet.se/~afb/lua/ You will need to convert all the line
endings to Macintosh format and set the type/creator codes so that
the OS can read the files.
4. Building on Windows
----------------------
You need Mingw for compilation (www.mingw.org). You will have to
explicitly define the lua dll files when linking. For example, if Lua
5.0.2 is installed in /usr/local/ then you can issue the following
command:
make \
DEFS=-I/usr/local/include \
LIBS="/usr/local/bin/lua.dll /usr/local/bin/lualib.dll"
Another example where Lua 5.1 is installed in /usr/lua-5.1 will be:
make \
DEFS=-I/usr/lua-5.1/include \
LIBS=/usr/lua-5.1/bin/lua51.dll
This should generate luagl.dll, luaglut.dll and memarray.dll.
Using alternative GLUT implementations
======================================
Besides using GLUT proper, luaglut can build with alternative
GLUT implementations (freeglut, openglut or openglean). Just add
USE_FREEGLUT=1 or USE_OPENGLUT=1 or USE_OPENGLEAN=1 to the make
command. Besides linking with the proper library, luaglut will also
activate the extra API functions that may come with the respective
implementations.
Running Instructions
=====================
Example programs can be run on any platform by issuing the following
commands: "lua glut_demo1.lua" and/or "lua glut_demo2.lua"
Hopefully I'll write some documentation when I have time. Meanwhile,
you can look at the sources and the two examples that are provided.
List of files
=============
Main Sources:
-------------
README - this file
LICENCE - the licence
Makefile - the makefile
luagl.c - the C source for the OpenGL bindings
luaglut.c - the C source for the GLUT (and some GLU) bindings
memarray.c - the C source for the memarray library
macros.h - macros used in the compilation of above C sources
macros.lua - this lua file can be used to generates macros.h
menus.h - menus.lua in an embeded form (included in luaglut.c)
menus.lua - menu support code for GLUT
Helpers for library loading: (not necessary with Lua 5.1)
---------------------------------------------------------
luagl.lua - helper file for loading the dynamic library
luaglut.lua - helper file for loading the dynamic library
memarray.lua - helper file for loading the dynamic library
Examples:
---------
glut_test1.lua - simple example
glut_test2.lua - same as above, but with texture mapping
lua.ppm - texture loaded by glut_test2.lua
CodeWarrior / Carbon support files:
-----------------------------------
luagl.exp - library export information
luaglut.exp - library export information
memarray.exp - library export information
luaglut.prefix.h - Carbon support
Carbon.r - Needed to launch in OS X
luaglut.mcp.xml.gz - project file for importing in the CodeWarrior IDE
Varol Kaptan <varol.kaptan@gmail.com>