
       --- OpenGL/Mesa and Xlib bindings for CMU Common Lisp ---

These bindings are a modified version of Richard Mann's OpenGL/Xlib
bindings for Allegro Common Lisp.  GL, GLU, GLX and GLUT are accessed in
the package :GL, XLIB in the package :XLIB.


INSTALLAION

I have tried to create a Makefile that should make the compilation and
installation fairly easy.  Try following these steps:

1. Untar the bindings into the directory where you want it to be installed.

2. Edit the Makefile to reflect your Lisp, C compiler and Xlib/OpenGL
   libraries.

3. Run make.  Compilation will take a while.  The most likely cause of
   errors is unresoled symbols from libraries.  If this happens, edit
   the LIBS section in the makefile and try again.  (You may also have to
   run 'make clean' first.)

4. Test if it works by going into the examples/ dir, editing the makefile
   if necessary, and compiling/running the examples.
   [../run-lisp -load <file>, then run (main).]

5. If everything works, add a line to your ~/.cmucl-init.lisp file:
   (load "/[PATH-TO-CMUCL-XLIB-AND-GL]/defsystem")
   Now loading the GL and XLIB libraries can be done by running
   (load-gl) and (load-xlib).


Some notes:

* GLUT callbacks does not work, or at least I haven't found out how to
  define C callbacks in CMUCL.  That means you have to use GLX and XLIB
  to create windows, handle events and so on.  (GLUT utility functions such
  as glutSolidSphere() should work.)

* The bindings have been tested on Linux (Mesa) and Solaris, but:
  I can't get accelerated OpenGL to work with my TNT2 under Linux with
  XFree-4.0 or XFree-4.0.1.  It works from C, but when trying to initialize
  OpenGL through CMUCL, I get the error:
NV: could not map frame buffer on /dev/nvidia0, errno=12
  I don't know what it causing this (maybe something with the way CMUCL
  loads libraries dynamically?), please contact me if you have a
  suggestion.

* Arrays are passed as raw pointers to C functions, so they need to be
  specialized (this is the same as for Allegro).  In particular, an
  int[] array must be specialized as (SIGNED-BYTE 32), not FIXNUM.

* Most C pointers are represented as integers in Lisp, except array pointers
  which are explained above.  For most pointers to structures, a set of
  allocator, getter and setter functions has been added in C.  This is meant
  to be unchanged from the Allegro version.


FILES:

* cmucl-interface-defpackage.lisp, cmucl-interface.lisp:
  Definitions of the FOREIGN-FUNCTION and FOREIGN-DEFINE macros.

* gl-defpackage.lisp, gl.lisp, gl-c.c:
  Bindings for OpenGL/Mesa, GLU, GLUT, GLX.

* xlib-defpackage.lisp, xlib.lisp, xlib-c.lisp:
  Bindings for Xlib.

* Makefile, Makefile.sun:
  Modify before running make.

* load-libs.lisp, run-lisp, defsystem.lisp:
  These files are generated by running make.  load-libs.lisp loads the
  foreign GL and Xlib libraries, run-lisp is a script to run lisp and
  then load the libraries, and defsystem.lisp defines the functions
  LOAD-GL and LOAD-XLIB that can be called to load the GL and XLIB
  packages.  run-lisp and defsystem.lisp provide two different methods to
  load the bindings, you only need to use one of them.

* examples/:
  The examples directory has a few simple examples.  Since GLUT doesn't
  work (at least not yet), they are GLX examples, using Xlib to handle
  windows and events.

LICENCE

Since this is a modified version of Richard Mann's bindings, they use
the same licence.  See the file 'LICENCE'.


Have fun,

Knut Arild Erstad
knute@ii.uib.no
