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>