
       --- 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

This version uses defsystem instead of make.  It is less messy, but
not automatic, you still need to edit some parameters.  Try following
these steps:

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

2. Make sure mk:defsystem is installed and working.  (You should probably
   load it from your .cmucl-init file.)

3. Edit the parameters at the top of the 'xlib-and-gl.system' file to reflect
   your installation directory, C compiler/flags and Xlib/OpenGL libraries.

4. Compile and load 'xlib-and-gl.system' and run (make:compile-system :gl)
   and (make:compile-system :xlib).  Either do this manually or just type
   "make" on the Unix command line (you have to edit the Makefile first if
   your CMUCL executable is not named 'lisp').  The most likely cause of
   errors is unresolved symbols from libraries.  If this happens, edit the
   *LIBS* parameter and try again.

   Note: Don't skip compiling xlib-and-gl.system; I get errors (from
   LOAD-FOREIGN, I think) when trying to run in interpreted mode.

5. Test if it works by running the examples:
   (make:load-system :glx-examples), then run
   (bounce-glx:main) and (glspin-glx:main).
   (make:load-system :glut-examples), then
   (bounce-glut:main) and (glspin-glut:main).

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


Some notes:

* This version includes experimental GLUT bindings.  Please let me know
  if they don't work.  Just use (gl:glutDisplayFunc #'draw) and so on,
  or take a look at the file examples/glut-program.lisp.
  GLUT problems and notes:
  - Currently glutTimerFunc() does not work.
  - glutKeyboardFunc()'s first callback argument is a fixnum rather than a
    character; just use CODE-CHAR to get the keypress.
  - There is no "normal" exit from glutMainLoop(), but using THROW/CATCH
    should work.
  - On a Sparc/Solaris platform I use, glutDestroyWindow() doesn't work
    properly.  I think this could be a problem with Xlib (openwin) rather
    than GLUT...

* The Xlib bindings are not the same as CLX.  It would be nice to be able to
  use CLX with OpenGL, but currently I don't know how to do this.  The
  problem is that glX functions (for instance glXCreateContext) want C
  structures such as "Display *" as arguments, but CLX seems to have its own
  (Lisp) versions.  Suggestions are welcome.

* Things are generally compiled with high speed and low safety settings
  ((SPEED 3) (SAFETY 0)).  This means that arguments of the wrong type
  are passed along without warnings or errors, so be careful.  If you
  want to change the safety settings, look at the FOREIGN-FUNCTION
  macro in cmucl-interface.lisp.

* Arrays are passed as raw pointers to C functions, so they need to be
  specialized simple-vectors.  (This is similar to the Allegro version.)
  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.

* The bindings have been tested on Linux and Solaris, and seem to be working.
  I used to get a cryptic error message when trying to use nVidia's
  accelerated driver with my TNT2:
NV: could not map frame buffer on /dev/nvidia0, errno=12
  After upgrading to a newer version of CMUCL, the problem disappeared.
  I think this may have something to do with the glibc version CMUCL was
  compiled under, but your guess is as good as mine.  If you get similar
  errors, try a new CMUCL binary and let me know if it works.


FILES:

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

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

* glut-interface.lisp, glut-callbacks.lisp, glut-callbacks-c.c:
  Experimental support for GLUT callbacks.

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

* xlib-and-gl.system, Makefile:
  Defsystem/make.  Modify these before building.

* README, LICENSE
  Text.

* examples/:
  The directory has a few simple examples.


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
