LablGL 1.06: 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.

  https://github.com/garrigue/lablgl
  http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgl.html

2. Requisites

  * Objective Caml 3.05 to 4.08
  * Compatible version of Camlp5 (or Camlp4, see Makefile.common)
  * 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://ocaml.org

  OpenGL (with hardware support) may already be on your machine.
  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.7). 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 Unix versions. For Linux, just install the package.

Windows binary distribution:
  The file lablgl-1.05-win32.zip supports the mingw windows installer
  for ocaml 4.01.

  a) Install the lablGL distribution.
     The simplest way is to use the command-line version of unzip, and
     unpack it on top of your Objective Caml distribution.
        C:\Program Files\Objective Caml> unzip lablgl-1.04-win32.zip
     If you unpacked it somewhere else you must copy manually the
     contents of the bin, lib\stublibs and lib\lablGL directories to
     the corresponding directories of the Objective Caml distribution.

  b) Compile the Caml parts.
     Go to the lib\lablGL directory, and execute the following command 
        C:\...\lib\lablGL\> ocaml build.ml
     It will generate the bytecode and native versions of the library.
     Note that every time you install a new version of Objective Caml
     you will need to repeat this last step.
     Look carefully at the last line of output of this script, it should
     tell you which ocaml port you are using. If the guess is wrong, you
     edit build.ml to correct this.

  c) For glut support, download glut32.dll and copy it to the bin
     directory of the OCaml distribution (or somewhere else in your
     path.)

  After this, you should be able to compile and run programs as either
  bytecode or native code.

Compilation from source (if there is no package):

  0) On MacOSX, if you want to use Togl, you must use the X11 version
     of Tcl/Tk. Here we assume that ocaml was installed from macports.
     Then you must also install the mesa port from macports, to obtain
     a compatible version of GLX.

  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.   

  To compile for Windows, Makefile.config.msvc and
  Makefile.config.mingw are provided. Note however that the DLL
  produced for Togl by mingw does not work with the ocaml 3.11 binary
  distribution, you must use the one   produced by MSVC, included in
  the binary distribution above.

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

   https://github.com/garrigue/lablgl/issues

   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
   glGetError

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
   glPolygonOffset
   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
   glScissor
   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.