[ocaml-opengl] OpenGL {3, 4} and OpenGL ES {2, 3} bindings, testers welcome.

[Daniel Bünzli]

Hello,

I made thin, low-level, ocaml-ctypes bindings to OpenGL 3.{2,3},
4.{0,1,2,3,4} and OpenGL ES {2,3}. They are automatically generated
from the offical XML representation of the OpenGL Registry [1].

These bindings are neither tested nor used and interfaces are still
subject to change. Testers are welcome; report any problems you may
encounter on github's infrastructure. Have a look at the readme to
understand how these libraries are structured:

  https://github.com/dbuenzli/tgls/blob/master/README.md#supported-opengl-versions

The documentation of the bindings is here:

  http://erratique.ch/software/tgls/doc/

To install (only tested on osx with OpenGL 3.2 and linux or raspberry 
pi with OpenGL ES 2 so far) you'll need `curl` and `xmlm` installed on 
your system. This is only for this pre-release, actual distribution will
have the generated bindings. Then:

  opam repo add erratique-u http://erratique.ch/software/opam/unreleased
  opam update && opam install xmlm tgls

Sample code (needs tsdl, `opam install tsdl`), is in the directory 
`opam config var tgls:doc`.

If you want to hack the source first have a read at:

  https://github.com/dbuenzli/tgls/blob/master/DEVEL.md 

then:

  git clone http://github.com/dbuenzli/tgls 
  cd tgls && ./build support && ./build trigl3.native && ./trigl3.native

A few notes:

* This time the cryptic acronym is [T]hin bindings to Open[GL] librarie[S].
  No need to waste everybody's time with alternate name suggestions:
  it won't change. 

* ocaml-ctypes was used as this was the shortest path to get the
  work done, using it should also solve the problem of getting the
  OpenGL function pointers. However the support for reading and making
  sense of the OpenGL registry being done, regular OCaml stubs could
  also be generated in the future if ctypes turns out to be a
  bottleneck.

* There's one OCaml library per major OpenGL release (which correspond
  to GPU hardware generations). Such a library has all the entry
  points and enumerants for supporting all the core (and only core)
  profiles of each minor releases of the major release. If you are
  programming with let's say 4.3 context it's your duty not to use a
  4.4 entry point/enumerant.

* I tried to include the C OpenGL libraries link flags in the OCaml ones
  so that OCamler's can just use the package with ocamlfind to
  build. Please report anything that may be missing. The current logic
  is as follows. On Darwin for tgl{3,4} we link against the OpenGL
  framework and nothing is done for tgles{2,3}. On linux pkg-config is
  used when packages can be found: gl for tgl{3,4}, glesv2 for tgles2
  and glesv3 (does that exist ?) for tgles3. Raspberry pi is like
  linux but tgles2 links to the pi's GLESv2 library located in
  /opt/vc/lib (would be nice from them to use pkg-config). 


* A single type represents all GLenums. Types for subsets could 
  be devised to enhance the signature/documentation of functions. This
  was not done for now since it seems the data from the registry is
  not clean/up to date (according to the registry's manual). However,
  the documentation links to the entry point's documentation and
  indicates the name of argument variables which should help to invoke
  the functions correctly (could have automatically derived labelled
  arguments but I thought that doing so systematically would result in
  a cumbersome API).

* The binding is very raw and can be unsafe. It could
  be made safer by either:

  1) Making more manual work, checking some bounds, automatically
     deriving some arguments for sizes. Doing that automatically in
     general is non trivial: for OpenGL 4.4 there are ~300 out of ~550
     entry points with pointer arguments, the registry has an
     attribute that should describe how the length of the pointer is
     to be determined but according to the registry's manual its
     syntax is poorely defined.

  2) Devising higher-level APIs that ensure type safety. 

  I tend to lean in favour of 2) OpenGL being so low-level and
  tiresome (rendering a colored triangle in "modern" OpenGL is a few
  hunderds of loc) that you'll anyway build an abstraction
  (a.k.a. rendering engine) on top of it.

* Binding generation is almost entirely automatic and type directed. 
  At the moment for OpenGL 4.4 there are only 7 out of 543 entry
  points that are manually devised. One thing that did require manual
  work though, was to enrich the registry information to indicate
  whenever null pointers can be specified for pointer arguments to map
  them to option types as the registry does unfortunately not specify that.

* There's no direct for support compatibility profiles or extensions. 
  Nowadays it's easy enough to use directly ocaml-ctypes (extensions
  usually add only a few entry points and/or enumerants). Alternatively 
  tgls' generation infrastructure could be used as the extensions are also 
  described in the registry but that may be overkill (some steps have been 
  done in that direction but it's not a priority right now for me).

I hope tgls can be a good starting point to get up to date OCaml
OpenGL bindings as work for supporting new versions should be minimal
provided they update the XML registry (which they should do since they
use it to generate the C headers). A first release will be done in a
few months, after the bindings will have been used a little bit by
myself. Meanwhile your feedback is welcome. 

Best,

Daniel

[1] http://www.opengl.org/registry/#specfiles