

		 OPENGL/MESA Bindings for Allegro Common Lisp

These bindings allow calls to OPENGL/MESA functions from Allegro Common Lisp.
The libraries GL, GLU, GLX, and GLUT are loaded dynamically and accessed
in the package :GL.

In addition, I have created a set of bindings to XLIB (in the package :XLIB).
This package is similar to CLX, except that the the shared library, libX11.so,
is loaded dynamically and the Xlib functions are called directly.  The reason
I did this is because I want to use a standard set of X functions from several
different Scheme and LISP implementations.

This code is based on an earlier release (in November and December of 1996) of
GL and XLIB bindings for GCL (Gnu Common Lisp) and Scheme (Scheme-to-C).
(See http://www.cs.toronto.edu/~mann).  Note: the previous release did not
provide bindings to GLUT.

If you have any suggestions, or find this interface useful, please let me
know.  In particular, I would like to know how many people are using LISP or
Scheme for vision, graphics, and application programming.  I don't want to use
C or C++ just because the required libraries (GL, XLIB) are in those
languagues!

Thanks,

Richard Mann
NEC Research Institute, Inc
4 Independence Way
Princeton NJ 08540-6620 USA
Tel: 609/951-2756
Fax: 609/951-2483
mann@research.nj.nec.com
http://www.neci.nj.nec.com/homepages/mann
18 May 1998


				    FILES

defsystem.lisp: Installation file (see below).

xlib-defpackage.lisp, xlib.lisp, xlib-c.c: The Lisp and C accessors for Xlib.
The file xlib-defpackage.lisp sets up the package (:XLIB) and exports the
appropriate symbols.

gl-defpackage.lisp, gl.lisp, gl-c.c: Lisp and C accessors for GL, GLU, GLX,
and GLUT.

examples/: Several sample programmings, using both Xlib and Glut for opening
windows and event handling.

examples/pnm.lsp: A set of accessors for PNM images (PBM images are bitmap;
PGM images are grey level; PPM images are color).  These functions allow
reading and writing of images.  Images are stored as "packed" byte arrays.  In
addition, this file provides accessors that give pointers to the pixel arrays
to pass to XLIB or GL functions requiring image data.

examples/sample.pgm, sample.ppm: sample images (for use by program
glimage.lisp).

work-in-progress/: Programs that are not working yet.


				 INSTALLATION

0. You need to have Allegro Common Lisp (ACL) version 4.3.  You also need to
   have OpenGL or Mesa, and GLUT installed on your system.  (I used Mesa
   version 2.6, which comes with GLUT version 3.6.)

1. Edit defsystem.lisp to conform to your system.  Note that the compiler
   options are those that make shared objects on a Linux ELF system.  Also set
   the correct location of the libraries (libGL.so, libGLU.so, libglut.so, and
   libX11.so) on your system.

2. Type (load "defsystem"), then (build-all) to build system.  Type
   (load-xlib) to load the :XLIB package and (load-gl) to load the :GL
   package.  (Note: not all programs need Xlib; The programs that use GLUT for
   the event loop only need :GL.)

   Note: If you get undefined symbols while trying to load shared objects
   you may have to relink them.  The file make-shared-libs shows an example
   of how to do this (for Linux).  What this does is takes statically linked
   libraries (*.a files) and creates shared objects (*.so files).  However,
   each shared object must have all symbols resolved *at link time* or else it
   will not load properly into Allegro Common Lisp.


		   NOTES ON THE FOREIGN FUNCTION INTERFACE

To interface to the GL and XLIB libraries I need to build a foreign function
interface to these functions in LISP.  The general philosophy is to write
"general" definitions for the C functions and macros (see the files gl.lisp,
xlib.lisp).  I then use the macros in allegro-interface.lisp to translate
these definitions to the specific form needed by LISP.

For most functions, LISP can call C functions directly.  (The conversion of
types is done automatically by LISP.)  This works when the arguments are
primitive types (char, int, float, double) or strings.  Problems arise,
however, when we want a C function to return a value to one of its arguments
or when we need to pass a pointer to some "composite" data structure (ie., an
array or a structure).

The general philosophy adopted here is to treat "composite" values (pointers
to primitive objects, pointers to structs, pointers to arrays) as raw
pointers.  Pointers are represented by integers in LISP and void* in C.

Typically, we allocate arrays in LISP and pass a pointer to any C function
that needs to access the array.  The main thing to watch out for is that in
the LISP arrays must be *contiguous* and of the correct type (such as byte,
fixnum, float or double).  We could also allocate the arrays on the C side,
but in most cases, we choose to allocate on the LISP side since we don't want
to build a whole new set of accessors for low-level C arrays.

For structs, however, we generally allocate and access them on the C side.  It
is possible to allocate structs on the LISP side and pass pointers to C
functions, but we do not do this here.

For examples of how to use this FFI, see the sample programs described above.


			   NOTE ON GL, XLIB and GLX

GL provides functions to do rendering, but it doesn't provide any functions to
open windows and manage events.

There are two ways to do this.  1) Using XLIB and the GLX routines, 2) Using
GLUT.  I show examples of both types of interfaces in the examples/
directory.  Note that for the XLIB/GLX case, the event loop must be handled by
the LISP program.  For the GLUT case, GL handles the event loop, but the user
must provide LISP procedures that act as callbacks.


				 THINGS TO DO

1. Some of the programs don't work correctly (drawing doesn't work or events
   are not handled correctly).  I'm not sure whether this has to do with Xlib,
   GL, or GLUT.  Furthermore, I'm not sure how this differs from SGI OpenGL
   and Mesa.

2. Is there a way to handle dynamic loading of shared libraries into Allegro
   Common LISP?  It would be nice not to have to relink libraries to get rid
   of the unresolved symbols problem.


                               ACKNOWLEDGEMENTS

Thanks to Brian Paul, for providing a free alternative to OpenGL!

Thanks to Franz Inc, for providing a Free version of Allegro Common LISP for
Linux.

The original bindings were generated using (a modified version of) FFIGEN from
Lars Thomas Hansen (lth@cs.uoregon.edu).

Thanks for Jeffrey Mark Siskind (NEC Research Institute) for help with the
LISP package system.


				   LICENSE

Copyright (c) 1998, NEC Research Institute Inc. All rights reserved.

Permission to use, copy, modify, and distribute this software and its
associated documentation for non-commercial purposes is hereby granted,
provided that the above copyright notice appears in all copies, derivative
works or modified version of the software and any portions thereof, and that
both the copyright notice and this permission notice appear in the
documentation.  NEC Research Institute Inc. shall be given a copy of any such
derivative work or modified version of the software and NEC Research Institute
Inc. and its affiliated companies (collectively referred to as NECI) shall be
granted permission to use, copy, modify and distribute the software for
internal use and research.  The name of NEC Research Institute Inc. and its
affiliated companies shall not be used in advertising or publicity related to
the distribution of this software, without the prior written consent of NECI.
All copies, derivative works or modified versions of the software shall be
exported or reexported in accordance with applicable laws and regulations
relating to export control.  This software is experimental.  NECI does not
make any representations regarding the suitability of this software for any
purpose and NECI will not support the software.  THE SOFTWARE IS PROVIDED AS
IS.  NECI DOES NOT MAKE ANY WARRANTIES EITHER EXPRESS OR IMPLIED WITH REGARD
TO THE SOFTWARE.  NECI ALSO DISCLAIMS ANY WARRANTY THAT THE SOFTWARE IS FREE
OF INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHTS OF OTHERS.  NO OTHER
LICENSE EXPRESS OR IMPLIED IS HEREBY GRANTED.  NECI SHALL NOT BE LIABLE FOR
ANY DAMAGES, INCLUDING GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE.

NOTE: If you want to use this software for purposes outside this license,
please contact me or my employer.
