
		LablGL 1.01: Installation and Use instructions

1. Description

  LablGL is an OpenGL interface for Objective Caml. It includes two
interfaces: the Togl widget, for comfortable use with LablTk, and
LablGlut for standalone applications not using Tcl/Tk

2. Requisites

  * Objective Caml 3.05 to 3.08
  * LablTk (included in Objective Caml, requires Tcl/Tk) for Togl support
  * OpenGL
  * glut (included in Mesa) for glut support
  * GNU make (for conditionals)

  Objective Caml can be obtained from
	http://caml.inria.fr/ocaml/

  OpenGL (with hardware support) is already on your machine on SGI and
most DEC Alpha systems. It may also be the case with Solaris machines,
and if you do not have it you may obtain it from Sun.
  XFree86 supports the GLX protocol since version 4.0, with hardware
acceleration on some platforms. It is available on most recent Linux
configurations.
  If you are not lucky enough to have built-in OpenGL support, you can
still use Mesa, an openGL-compatible freeware, which works on almost
everything.
	http://www.mesa3d.org/

  LablGl also uses the Togl widget, but the code is already included
in this distribution (version 1.5). You may obtain more information
about Togl at:
	http://www.mesa3d.org/brianp/Togl.html
Note that Togl is only compatible with vanilla Tcl/Tk: specially
patched versions may not work. For instance 8.2.3+ included in old
debian distributions does not work.

  LablGlut requires glut, which is already included in recent versions
of Mesa and XFree86. For windows you need to obtain it from
	http://www.xmission.com/~nate/glut.html

3. Installation

Precompiled versions of lablGL are available for windows, and a number
of Linux distributions. In this case you just have to install
necessary packages. Otherwise, compile from source.

  a) Create Makefile.config.
     Some tested configurations are provided.
     If none of them fits your needs, start with Makefile.config.ex.

  b) Build LablGL with both Togl(Tcl/Tk) and Glut support.
	% make

     If you need only Togl support, do
        % make togl
     If you need only Glut support, do
        % make glut
     If you need neither (use the library with lablGtk for instance)
        % make lib


  c) For the native code version (you need the native code version of LablTk),
	% make opt

     Similarly, you can also do
        % make {toglopt,glutopt,libopt}

  d) Install LablGL
	% make install

     This will install all the available parts.   


  With the windows binary distribution, copy bin\lablgl.bat,
  lib\stublibs\*.dll and lib\lablGL to their respective subdirectories
  in the OCaml distribution. For glut support, copy glut32.dll to
  the bin directory of the OCaml distribution (or somewhere else in
  your path).

  To compile for Windows, Makefile.config.msvc and
  Makefile.config.mingw are provided.

4. Use

  Examples are in the Togl/examples and LablGlut/examples directories.

  * The lablgl toplevel
    This is a toplevel, like ocaml, including LablTk, Unix, Str, LablGL
    and Togl.
    You may use it either as a toplevel, or directly to run scripts.
    To run an example in Togl/examples, type:
        % lablgl example.ml
    where example.ml is one of: (by order of complexity)
 	simple.ml
	scene.ml
	checker.ml	
	double.ml
	planet.ml
	texturesurf.ml
	gears.ml
	morph3d.ml
	tennis.ml

   Note that some XFree86 do not seem to support single buffer
   rendering. The first 3 examples will not work in that case.

  * Similarely, there is a lablglut toplevel.
    For instance, move to the folder LablGlut/examples/lablGL and type

	% lablglut gears.ml

  * compiling and linking
    You need to include either labltk.cma, lablgl.cma and togl.cma or'
    lablgl.cma and lablglut.cma in your link:
        ocamlc -I +labltk -I +lablGL \
            labltk.cma lablgl.cma togl.cma ... -o program
        ocamlc -I +lablGL lablgl.cma lablglut.cma ... -o program

5. Writing programs

  All of the GL and GLU libraries are available. Read a good book
  about how to use these. Translating from OpenGL to LablGL is rather
  straightforward: there is a LablGL function for each OpenGL one.
  For ease of retrieving, both GL and GLU are cut in smaller modules
  of related functions.  See in appendix A which modules your function
  is in. By default it has the same name, gl or glu omited, and
  capitals replaced by underscores.  When arguments are labelled, the
  names are taken from the man page or the C prototype.

  OpenGL makes heavy use of enumerations, with names starting with
  GL_ or GLU_ . Since their meaning is often overloaded, they are all
  converted to polymorphic variants. In most cases just replace prefix
  by a backquote and convert to low case. When you have a doubt the
  best way is to have a look with OCamlBrowser.

  Using Togl is also straightforward. Everything works like in
  LablTk. You create an openGL widget with Togl.create, and then you
  apply various functions on it. See Togl's README in Togl/src/Togl/README
  for details.

  To use LablGlut you need to look at glut's documentation on your system.
  The approach is close to LablGL's.

6. Comments and bug reports

   mailto:garrigue@kurims.kyoto-u.ac.jp

   This library has been tested on a number of programs, but this is
   far from testing all of OpenGL functionality. There are bugs, but
   at least we didn't find any in our examples.

7. Authors

   Jacques Garrigue, Isaac Trotts, Erick Tryzelaar and Christophe
   Raffali participated to this release.

A. Modules

   There are 12 modules for GL and 5 modules for GLU.
   Modules marked with (*) contain LablGL specific functions.

Gl: Common data types and functions.
   glFlush
   glFinish
   glEnable
   glDisable
   glIsEnabled

GlArray: Array functions
   glEdgeFlagPointer    -> edge_flag
   glTexCoordPointer    -> tex_coord
   glIndexPointer       -> index
   glNormalPointer      -> normal
   glVertexPointer      -> vertex
   glEnableClientState  -> enable
   glDisableClientState -> disable
   glArrayElement       -> element
   glDrawArrays
   glDrawElements

GlClear: Clearing functions.
   glClear
   glClearAccum		-> accum
   glClearColor		-> color
   glClearDepth		-> depth
   glClearIndex		-> index
   glClearStencil	-> stencil

GlDraw: Drawing functions.
   glBegin		-> begins
   glColor
   glCullFace
   glEdgeFlag
   glEnd		-> ends
   glFrontFace
   glIndex
   glLineStipple
   glLineWidth
   glNormal
   glPointSize
   glPolygonMode
   glPolygonStipple
   glRect
   glShadeModel
   glVertex
   glViewport

GlFunc: Filtering functions.
   glAccum
   glAlphaFunc
   glBlendFunc
   glColorMask
   glDepthFunc
   glDepthMask
   glDrawBuffer
   glIndexMask
   glLogicOp   
   glReadBuffer   
   glStencilFunc
   glStencilMask
   glStencilOp

GlLight: Lighting functions.
   glColorMaterial
   glFog
   glLight
   glLightModel (gl 1.2 with `color_control)
   glMaterial

GlList: Call list functions. (*)
   glCallList		-> call
   glCallLists
   glDeleteLists
   glEndList		-> ends
   glGenLists
   glIsList
   glNewList		-> begins

GlMap: Map and meshes functions.
   glEvalCoord1
   glEvalCoord2
   glEvalMesh1
   glEvalMesh2
   glEvalPoint1
   glEvalPoint2
   glMap1
   glMap2
   glMapGrid1		-> grid1
   glMapGrid2		-> grid2

GlMat: Matrix functions. (*)
   glFrustum
   glLoadIdentity
   glLoadMatrix		       -> load
   glLoadTransposeMatrix -> load_transpose (gl 1.3)
   glMatrixMode	 	       -> mode
   glMultMatrix		       -> mult
   glMultTransposeMatrix -> mult_transpose (gl 1.3)
   glOrtho
   glPopMatrix	      	 -> pop
   glPushMatrix	      	 -> push
   glRotate
   glScale
   glTranslate
   glGetDoublev          -> get_matrix (only for modelview, projection, and texture)

GlMisc: Miscellanous functions.
   glClipPlane
   glGetString
   glHint
   glInitNames
   glLoadName
   glPassThrough
   glPopAttrib
   glPopName
   glPushAttrib
   glPushName
   glRenderMode
   glSelectBuffer

GlPix: Rasterized pixel functions. (*)
   glBitmap
   glCopyPixels		-> copy
   glDrawPixels		-> draw
   glPixelMap		-> map
   glPixelStore		-> store
   glPixelTransfer	-> transfer
   glPixelZoom		-> zoom
   glRasterPos
   glReadPixels		-> read

GlTex: Texturing functions.
   glTexCoord		-> coord
   glTexEnv		-> env
   glTexGen		-> gen
   glTexImage1D		-> image1d
   glTexImage2D		-> image2d
   glTexParameter	-> parameter (gl 1.4 with generate_mipmap)

GluMat: GLU matrix functions.
   gluLookAt
   gluOrtho2D
   gluPerspective
   gluPickMatrix
   gluProject
   gluUnProject

GluMisc: GLU miscellanous functions.
   gluBuild1DMipmaps
   gluBuild2DMipmaps
   gluGetString
   gluScaleImage

GluNurbs: Nurbs functions.
   gluBeginCurve
   gluBeginSurface
   gluBeginTrim
   gluEndCurve
   gluEndSurface
   gluEndTrim
   gluLoadSamplingMatrices
   gluNewNurbsRenderer	-> create
   gluNurbsCurve	-> curve
   gluNurbsProperty	-> property
   gluNurbsPwlCurve	-> pwl_curve
   gluNurbsSurface	-> surface

GluQuadric: Quadric functions.
   gluCylinder
   gluDisk
   gluNewQuadric	-> create
   gluPartialDisk
   gluQuadricDrawStyle	-> draw_style
   gluQuadricNormals	-> normals
   gluQuadricOrientation -> orientation
   gluQuadricTexture	-> texture
   gluSphere

GluTess: Tessalating functions.
   Only glu 1.2 API is supported.
   Either render directly or produce lists of triangles.

$Id: README,v 1.35 2004/07/15 01:04:10 garrigue Exp $
