Repository files navigation

AGLFW binding for OCaml.

The current release is version3.3.1-2. Please install the GLFW library and its development files before attempting to install GLFW-OCaml.

Opam is a package manager for OCaml. This is the recommended way, simply run:

opam install glfw-ocaml

or if you would rather use the latest revision:

opam pin git+https://github.com/SylvainBoilard/GLFW-OCaml.git

GLFW-OCaml usesDune as its build system. Fetch the source by running:

wget https://github.com/SylvainBoilard/GLFW-OCaml/archive/3.3.1-2.zipunzip GLFW-OCaml-3.3.1-2.zipcd GLFW-OCaml-3.3.1-2

or for the latest revision:

git clone https://github.com/SylvainBoilard/GLFW-OCaml.gitcd GLFW-OCaml

Then build and install by running:

dune builddune install --prefix=<install_directory> # For example "/usr/local" or "/opt" (run as root)

GLFW-OCaml is a pretty straight-forward binding from the original API. Please refer tothe GLFW manual for detailed information. All functions and values are found in moduleGLFW.

Functions have theglfw prefix removed and their first letter uncapitalized. For exampleglfwCreateWindow would becomecreateWindow.

Values have theGLFW_ and where appropriate theKEY_ orMOD_ prefixes removed, are converted to PascalCase and typed according to their usage. For exampleGLFW_KEY_LEFT_BRACKET would become constructorLeftBracket of typekey andGLFW_NO_RESET_NOTIFICATION would become constructorNoResetNotification of typecontext_robustness. Names with a single letter prefix directly appended such asGLFW_IBEAM_CURSOR becomeIBeamCursor.

Instead of defining values for individual mouse buttons and joysticks, a plain 0-indexed number is used, although there aremouse_button_{left,right,middle} values defined for the most common mouse buttons. The maximum number of mouse buttons and connected joysticks can be accessed with themouse_button_max_count andjoystick_max_count values.

Window hints, attributes and input modes make use of GADTs to retain the polymorphic aspect of the corresponding original functions while ensuring type correctness.

Unlike the other functions where you can omit the labels of arguments, you will find you have to use them withgetWindowAttrib andgetInputMode. This is because the return type of these functions is polymorphic and the compiler will try to put any unlabeled arguments there. This makes for most peculiar errors.

Errors are propagated with exceptions instead of through a callback function. While there is a definition for anInvalidEnum exception, one should never be raised if you are not using unsafe features; otherwise that would be a GLFW-OCaml bug.

There is no need for user pointers in GLFW-OCaml as you can capture your data inside a closure and use that closure as a callback function while preserving type information.

TheGammaRamp module provides two functionscreate andmake to create gamma ramps while insuring all channels have the same length. The former builds a gamma ramp from three user-supplied channels while the later builds an empty gamma ramp with three channels of the supplied length. You can freely access and modify the contents of an existing gamma ramp but are required to use one of these functions to build one.

TheImage module likewise provides acreate function to create an image from raw pixel data with acceptable dimensions. Once created the dimensions of an image are immutable but you can still change its pixels by modifying the byte array.

Some of the original functions return their result via pointer arguments. In GLFW-OCaml these functions instead return a tuple with the individual elements in the same order as they appear in the original function.

WhereverGLFW_DONT_CARE or aNULL pointer would be a legal value, an option type is used to wrap the value andNone is used to representGLFW_DONT_CARE orNULL.

TheglfwGetProcAddress function is not supported because it would require writing an entire OpenGL wrapper to make the functions returned by GLFW usable from OCaml. There are several OpenGL bindings available for OCaml that you can use instead.

The Vulkan related functions are not supported as of now but we might look into it at some point or on request.