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