lablgl

lablgl copied to clipboard

	LablGL 1.07: 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 since 4.14
• LablTk (included in Objective Caml, requires Tcl/Tk) for Togl support (only works for Tcl/Tk older than 8.4)
• 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 older than 8.4: specially patched versions may not work. For instance 8.2.3+ included in old debian distributions does not work, and recent versions do not work either.

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.