Consult the basics. Open the module to use it, this defines only modules and types in your scope.
Release 0.8.0 - Daniel Bünzli <daniel.buenzl firstname.lastname@example.org>
An n-dimensional vector
v is a sequence of n, zero indexed,
floating point components. We write
vi the ith component
of a vector.
module type V =
An n-dimensional point
p is a vector of the corresponding
dimension. The components of the vector are the point's coordinates.
module type P =
represent rotations in 3D space. They allow to smoothly
interpolate between orientations. A quaternion is a 4D vector,
w represents the quaternion
An mxn matrix
a is an array of m rows and n
columns of floating point elements. We write
a located at the ith row and jth column.
Matrix constructors specify matrix elements in
so that matrix definitions look mathematically natural with proper
code indentation. However elements are stored and iterated over in
module type M =
An n-dimensional size
s represents extents in n-dimensional space.
module type Size =
An n-dimensional axis-aligned box
b is defined by an
o, its origin, and an n-dimensional size
s. Operations on boxes with negative sizes are undefined.
The space S(
b) spanned by
b is [
s0] x ... x [
sn-1]. The extremum points of this space are the box's corners. There is a distinguished n-dimensional
empty box such
empty) is empty.
module type Box =
Gg is designed to be opened in your module. This defines only
types and modules in your scope, no values. Thus to use
In the toplevel, if you installed
Gg with ocamlfind, requiring
> #require "gg";;
Ggand installs printers for the types.
Most types and their functions are defined with the following
conventions. The type is first defined in
Gg.v2 for 2D
vectors, a module for it follows. The name of the module is
the type name capitalized, e.g.
Gg.V2 for 2D vectors and it has
the following definitions:
tequal to the original toplevel type (
intvalue that indicates the dimensionality of the type (
v, a constructor for the type (
ppto convert values to a textual representation for debugging purposes and toplevel interaction (
comparethe standard functions that make a module a good functor argument (
compare_fwhich compare like
comparebut allow to use a client provided function to compare floats (
trto apply linear and affine transforms on the type (
Gg.V2.x), constants (e.g.
Gg.V2.zero), functions (e.g.
Gg.V2.dot) and predicates (e.g.
Gg.V2.exists) specific to the type.
Gg.V4for vectors, usually share a common signature. This common signature is collected in a module type defined in
Gg, this signature is
Some types are defined as simple abreviations. For example the
Gg.p2 for 2D points is equal to
Gg.v2. These types also have
a module whose name is the type name capitalized,
Gg.P2 in our
example. However this module only provides alternate constructors,
constants and accessors and the extended functionality specific to the
type. You should fallback on the module of the abreviated type
Gg.V2 in our example) for other operations. The aim of these
types is to make your code and signatures semantically clearer
without the burden of explicit conversions.
Finally there are some types and modules like
Gg.Color whose structure
is different because they provide specific functionality.
Here are a few other conventions :
Gg.M4.scale3indicates scale in 3D space wihle
Gg.M4.scalescale in 4D space.
of_conventions. Thus to convert a value of type
t'to a value of type
tlook for the function named
To conclude note that it is sometimes hard to find the right place for a function. If you cannot find a function look into each of the modules of the types you want to act upon.
Values of type
Gg.color are in a linear sRGB space as this is
the space to work in if you want to process colors correctly (e.g.
for blending). The constructor
Gg.Color.v_srgb takes its parameters
from a non-linear sRGB space and converts them to linear
This is the constructor you are likely to use when you specify color constants (e.g. to specify a color value matching a CSS color). If you need an sRGB color back from a
# let c = Color.v_srgb 0.5 0.5 0.5 1.0;;
- : Gg.color = (0.214041 0.214041 0.214041 1)
# Color.to_srgba c;;
- : Gg.Color.srgba = (0.5 0.5 0.5 1)
to_stringfunctions are not thread-safe. Thread-safety can be achieved with
Gg.Float's module printers that output a lossless textual representation of floats. While the actual format is subject to change it will remain compatible with
Map.Make. However this will use
Pervasives.compareand thus binary comparison between floats. Depending on the intended use this may be sensible or not. Comparisons with alternate functions to compare floats can be defined by using the functions named
Gg.V2.compare_f). An alternate float comparison function is
Gg.Float.compare_tolthat combines relative and absolute float comparison in a single test, see
Gg.Float.equal_tolfor the details.
Gg.Floatmodule are undefined on certain arguments but do not raise
Invalid_argumenton those. As usual do not rely on the behaviour of functions on undefined arguments, these are subject to change.