
		LablGL 0.96-beta: Installation and Use instructions

1. Description

  LablGL is an OpenGL interface for Objective Caml. Since it includes
support for the Togl widget, you can comfortably use it with LablTk.

2. Requisites

  * Objective Caml 3.03-alpha
  * LablTk (included in Objective Caml, requires Tcl/Tk)
  * OpenGL version 1.0 or 1.1

  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.
  If you are not lucky enough to have 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

3. Installation

  a) Edit Makefile.config

  b) Build LablGL
	% make

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

  d) Install LablGL
	% make install

4. Use

  * The lablgl toplevel
    This is a toplevel, like ocaml, including LablTk, Unix, Str and LablGL.
    You may use it either as a toplevel, or directly to run scripts.
    To run an example, type:
        % lablgl -labels 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

  * compiling and linking
    You need to include labltk.cma, lablgl.cma and togl.cmo in your link:
        ocamlc -I CAMLLIB/labltk -I CAMLLIB/lablGL \
            labltk.cma lablgl.cma togl.cmo ... -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
  straitforward: there is a LablGL function for each OpenGL one.  For
  ease of retrieving, bot 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 name is
  taken from the man page or the C prototype.

  OpenGL makes heavy using of enumerations, with names staring 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 LablBrowser.

  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 for details.

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.

A. Modules

   There are 11 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

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
   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
   glMatrixMode		-> mode
   glMultMatrix		-> mult
   glOrtho
   glPopMatrix		-> pop
   glPushMatrix		-> push
   glRotate
   glScale
   glTranslate

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

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.
   gluBeginPolygon	-> begins
   gluEndPolygon	-> ends
   gluNewTess		-> create
   gluTessBeginContour	-> begin_contour (1.2)
   gluTessBeginPolygon	-> begin_polygon (1.2)
   gluTessEndContour	-> end_contour	 (1.2)
   gluTessEndPolygon	-> end_polygon	 (1.2)
   gluTessNormal	-> normal	 (1.2)
   gluTessProperty	-> property	 (1.2)
   gluTessVertex	-> vertex
   (1.2) only available with GLU 1.2

$Id: README,v 1.13 2001/10/12 14:19:58 garrigue Exp $
