Module Gg

Basic types for computer graphics.

Gg defines types and functions for floats, vectors, points, matrices, quaternions, sizes, axis aligned boxes, colors, color profiles, linear bigarrays and raster data.

Consult the basics.

Open the module to use it, this defines only modules and types in your scope.

Floats

module Float : sig ... end

Floating point number utilities.

Vectors

An n-dimensional vector v is a sequence of n, zero indexed, floating point components. We write vi the ith component of a vector.

The matrix types are defined here so that they can be used in vector modules; their modules are here.

type m2

The type for 2x2 matrices.

type m3

The type for 3x3 matrices.

type m4

The type for 4x4 matrices.

type v2

The type for 2D vectors.

type v3

The type for 3D vectors.

type v4

The type for 4D vectors.

module type V = sig ... end

Implemented by all vector types.

module V2 : sig ... end

2D vectors.

module V3 : sig ... end

3D vectors.

module V4 : sig ... end

4D vectors.

Points

An n-dimensional point p is a vector of the corresponding dimension. The components of the vector are the point's coordinates.

type p2 = v2

The type for 2D points.

type p3 = v3

The type for 3D points.

module type P = sig ... end

Implemented by all point types.

module P2 : sig ... end

2D points.

module P3 : sig ... end

3D points.

Quaternions

Unit quaternions represent rotations in 3D space. They allow to smoothly interpolate between orientations. A quaternion is a 4D vector, whose components x, y, z, w represents the quaternion xi+ yj + zk + w.

type quat = v4

The type for quaternions.

module Quat : sig ... end

Quaternions.

Matrices

An mxn matrix a is an array of m rows and n columns of floating point elements. We write aij the element of a located at the ith row and jth column.

Matrix constructors specify matrix elements in row-major order so that matrix definitions look mathematically natural with proper code indentation. However elements are stored and iterated over in column-major order.

module type M = sig ... end

Implemented by all (square) matrix types.

module M2 : sig ... end

2D square matrices.

module M3 : sig ... end

3D square matrices.

module M4 : sig ... end

4D square matrices.

Sizes

An n-dimensional size s represents extents in n-dimensional space.

type size1 = float

The type for sizes in 1D space.

type size2 = v2

The type for sizes in 2D space.

type size3 = v3

The type for sizes in 3D space.

module type Size = sig ... end

Implemented by all size types.

module Size1 : sig ... end

Sizes in 1D space.

module Size2 : sig ... end

Sizes in 2D space.

module Size3 : sig ... end

Sizes in 3D spaces.

Axis-aligned boxes

An n-dimensional axis-aligned box b is defined by an n-dimensional point 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 [o0; o0 + s0] x ... x [on-1; on-1 + sn-1]. The extremum points of this space are the box's corners. There is a distinguished n-dimensional empty box such that S(empty) is empty.

type box1

The type for 1D axis-aligned boxes (closed intervals).

type box2

The type for 2D axis-aligned boxes (rectangles).

type box3

The type for 3D axis-aligned boxes (cuboids).

module type Box = sig ... end

Implemented by all axis-aligned box types.

module Box1 : sig ... end

1D axis-aligned boxes.

module Box2 : sig ... end

2D axis-aligned boxes.

module Box3 : sig ... end

3D axis-aligned boxes.

Colors

type color = v4

The type for colors, see details.

module Color : sig ... end

Colors and color profiles.

Linear bigarrays and bigarray buffers

type ('a, 'b) bigarray = ('a, 'b, Bigarray.c_layout) Bigarray.Array1.t

The type for linear bigarrays.

type buffer = [
  1. | `Int8 of (int, Bigarray.int8_signed_elt) bigarray
  2. | `Int16 of (int, Bigarray.int16_signed_elt) bigarray
  3. | `Int32 of (int32, Bigarray.int32_elt) bigarray
  4. | `Int64 of (int64, Bigarray.int64_elt) bigarray
  5. | `UInt8 of (int, Bigarray.int8_unsigned_elt) bigarray
  6. | `UInt16 of (int, Bigarray.int16_unsigned_elt) bigarray
  7. | `UInt32 of (int32, Bigarray.int32_elt) bigarray
  8. | `UInt64 of (int64, Bigarray.int64_elt) bigarray
  9. | `Float16 of (int, Bigarray.int16_unsigned_elt) bigarray
  10. | `Float32 of (float, Bigarray.float32_elt) bigarray
  11. | `Float64 of (float, Bigarray.float64_elt) bigarray
]

The type for linear bigarray buffers.

module Ba : sig ... end

Linear bigarrays and bigarray buffers.

Raster data

type raster

The type for raster data.

module Raster : sig ... end

Raster data.

Basics

Gg is designed to be opened in your module. This defines only types and modules in your scope, no values. Thus to use Gg start with :

open Gg

In the toplevel enter:

> #require "gg.top";;

to automatically open Gg and install printers for the types.

Conventions

Most types and their functions are defined with the following conventions. The type is first defined in Gg, like v2 for 2D vectors, a module for it follows. The name of the module is the type name capitalized, e.g. V2 for 2D vectors and it has the following definitions:

Some types are defined as simple abreviations. For example the type p2 for 2D points is equal to v2. These types also have a module whose name is the type name capitalized, 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 (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 Color whose structure is different because they provide specific functionality.

Here are a few other conventions :

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.

Mathematical conventions

Note on colors

Values of type 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 Color.v_srgb takes its parameters from a non-linear sRGB space and converts them to linear sRGB.

# let c = Color.v_srgb 0.5 0.5 0.5 1.0;;
- : Gg.color = (0.214041 0.214041 0.214041 1)

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 color value use Color.to_srgb:

# Color.to_srgba c;;
- : Gg.Color.srgba = (0.5 0.5 0.5 1)

Remarks and Tips