Safe Haskell	Safe-Inferred
Language	Haskell2010

Graphics.Caramia.Math

Contents

sizeOfs
4x4 matrices
3x3 matrices
quaternions
3-component vectors
- Lenses
Misc

Description

Matrix, vector and quaternion math module. This module is concerned about common functions for graphics programming and the types from this module are used by the rest of Caramia.

If you require more functionality or types, I suggest you look at a dedicated linear algebra package such as 'hmatrix' or 'linear'.

Matrix44, Matrix33, Quaternion and Vector3 are all Storables.

The matrices are stored as column vectors. That is, if a Matrix4 is labelled like this:

        Col.1  Col.2  Col.3  Col.4
       ---------------------------
Row 1    m11    m12    m13    m14
Row 2    m21    m22    m23    m24
Row 3    m31    m32    m33    m34
Row 4    m41    m42    m43    m44
       ---------------------------

The matrix would occupy memory (as a Storable) as follows:

  m11, m21, m31, m41, m12, m22, m32, m42, m13 ...

where each value is a 32-bit floating point value. This is what OpenGL uses.

(if the above matrix was a translation matrix, then m14, m24 and m34 would contain the x, y and z coordinates of a translation).

The scheme is the same for a Matrix33, just drop the fourth row and column.

Vector3 is stored as three consecutive floating point values.

  x, y, z

Quaternion first stores the w as the last element. So, the layout of a quaternion is:

  x, y, z, w

This is also how Shader maps quaternions to vectors in shaders.

Synopsis

Documentation

data Matrix44 Source

A 4x4 matrix. Each mXX function accesses an individual element of the matrix.

Constructors

Matrix44
Fields m11 :: !Float m21 :: !Float m31 :: !Float m41 :: !Float m12 :: !Float m22 :: !Float m32 :: !Float m42 :: !Float m13 :: !Float m23 :: !Float m33 :: !Float m43 :: !Float m14 :: !Float m24 :: !Float m34 :: !Float m44 :: !Float

Instances

Eq Matrix44
Ord Matrix44
Read Matrix44
Show Matrix44
Storable Matrix44
Uniformable Matrix44
Typeable * Matrix44

data Matrix33 Source

A 3x3 matrix. Each nXX function accesses an individual element of the matrix.

Constructors

Matrix33
Fields n11 :: !Float n21 :: !Float n31 :: !Float n12 :: !Float n22 :: !Float n32 :: !Float n13 :: !Float n23 :: !Float n33 :: !Float

Instances

Eq Matrix33
Ord Matrix33
Read Matrix33
Show Matrix33
Storable Matrix33
Uniformable Matrix33
Typeable * Matrix33

data Vector3 Source

A 3-dimensional vector. x, y and z access each individual component.

Constructors

Vector3
Fields x :: !Float y :: !Float z :: !Float

Instances

Eq Vector3
Ord Vector3
Read Vector3
Show Vector3
Storable Vector3
Uniformable Vector3
Typeable * Vector3

data Quaternion Source

A quaternion. It's composed of four values, qx, qy, qz and qw.

In the context of Caramia, quaternions are used exclusively to represent rotations.

Constructors

Quaternion
Fields qx :: !Float qy :: !Float qz :: !Float qw :: !Float

Instances

Eq Quaternion
Ord Quaternion
Read Quaternion
Show Quaternion
Storable Quaternion
Uniformable Quaternion
Typeable * Quaternion

sizeOfs

sizeOfMatrix44 :: Int Source

Returns the size of a Matrix4. This is just a shortcut to calling sizeOf on a matrix.

sizeOfMatrix33 :: Int Source

Returns the size of a Matrix3. This is just a shortcut to calling sizeOf on a matrix.

sizeOfVector3 :: Int Source

Returns the size of a Vector3. This is just a shortcut to calling sizeOf on a vector.

sizeOfQuaternion :: Int Source

Returns the size of a Quaternion. This is just a shortcut to calling sizeOf on a quaternion.

4x4 matrices

matrix44 :: Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Matrix44 Source

Constructs a Matrix44 out of 16 values.

The order of the values is column-first. That is, in this order:

   m11 m12 m13 m14 m21 m22 m23 m24 m31 ...

This allows you to write the matrix out this way:

  let the_greatest_4x4_matrix_of_them_all =
         matrix4 m11 m12 m13 m14
                 m21 m22 m23 m24
                 m31 m32 m33 m34
                 m41 m42 m43 m44
   in ...

withMatrix44Ptr Source

Arguments

:: Matrix44	The matrix to marshal.
-> (Ptr CFloat -> IO a)	An IO action that receives a pointer to floating point values describing the matrix.
-> IO a

Runs an IO action with a pointer to a Matrix44. The pointer is valid only during the given IO action.

The pointer points to an array of 16 floating point values. See Caramia.Math for a description in which order the values appear.

inverse44 :: Matrix44 -> Matrix44 Source

Calculates the inverse of a 4x4 matrix.

A matrix doesn't always have an inverse. In this case, the matrix values will most likely end up being NaNs.

identity44 :: Matrix44 Source

Returns the identity 4x4 matrix.

multiply44 :: Matrix44 -> Matrix44 -> Matrix44 Source

Multiplies two 4x4 matrices together.

determinant44 :: Matrix44 -> Float Source

Calculates the determinant of a 4x4 matrix.

zero44 :: Matrix44 Source

Returns the 4x4 matrix where all components are zero.

perspective44 Source

Arguments

:: Float	Field of view in radians.
-> Float	Aspect ratio.
-> Float	Near plane distance.
-> Float	Far plane distance.
-> Matrix44

Constructs a perspective projection matrix.

distance44 :: Matrix44 -> Matrix44 -> Float Source

Returns the Euclidean distance between two 4x4 matrices, where the matrices are taken to be 9-vectors.

This can be used as a rough estimate how close, or similar two matrices are to each other.

frustum44 Source

Arguments

:: Float	Left plane.
-> Float	Right plane.
-> Float	Bottom plane.
-> Float	Top plane.
-> Float	Near plane.
-> Float	Far plane.
-> Matrix44

Constructs a perspective projection matrix by frustum planes.

ortho44 Source

Arguments

:: Float	Left plane.
-> Float	Right plane.
-> Float	Bottom plane.
-> Float	Top plane.
-> Float	Near plane.
-> Float	Far plane.
-> Matrix44

Constructs an orthogonal projection matrix by planes.

lookat44 Source

Arguments

:: Vector3	Eye position.
-> Vector3	Center position (that is, the point we are going to stare at).
-> Vector3	Up vector. You probably want to normalize this.
-> Matrix44

Constructs a look-at view matrix.

translate44 Source

Arguments

:: Vector3	The translation vector.
-> Matrix44	The matrix to modify.
-> Matrix44

Modifies a 4x4 matrix to include translation.

This is the same as multiplying a 4x4 matrix with a translation matrix.

transpose44 :: Matrix44 -> Matrix44 Source

Transposes a 4x4 matrix.

scale44 Source

Arguments

:: Vector3	The scale vector.
-> Matrix44	The matrix to modify.
-> Matrix44

Modify a 4x4 matrix to scale everything by given vector.

rotate44 Source

Arguments

:: Float	The angle, how much to rotate. In radians.
-> Vector3	The rotation axis.
-> Matrix44	The matrix to modify.
-> Matrix44

Modifies a 4x4 matrix to include rotation as specified by an axis-angle representation.

This is the same as multiplying a matrix with a rotation matrix.

3x3 matrices

matrix33 :: Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Matrix33 Source

Constructs a Matrix3 out of 9 values.

The order of the values is the same as for matrix4, just drop the fourth row and column.

withMatrix33Ptr :: Matrix33 -> (Ptr CFloat -> IO a) -> IO a Source

Same as withMatrix44Ptr, only with 9 floating values.

inverse33 :: Matrix33 -> Matrix33 Source

Calculats the inverse of a 3x3 matrix.

A matrix doesn't always have an inverse. In this case, the matrix values will most likely end up being NaNs.

identity33 :: Matrix33 Source

Returns the identity 3x3 matrix.

multiply33 :: Matrix33 -> Matrix33 -> Matrix33 Source

Multiplies two 3x3 matrices together.

determinant33 :: Matrix33 -> Float Source

Calculates the determinant of a 3x3 matrix.

zero33 :: Matrix33 Source

Returns the 3x3 matrix where all components are zero.

distance33 :: Matrix33 -> Matrix33 -> Float Source

Returns the Euclidean distance between two 3x3 matrices, where the matrices are taken to be 9-vectors.

This can be used as a rough estimate how close, or similar two matrices are to each other.

transpose33 :: Matrix33 -> Matrix33 Source

Transposes a 3x3 matrix.

matrix33ToMatrix44 :: Matrix33 -> Matrix44 Source

Transforms a Matrix33 into a Matrix44.

If this is the original 3x3 matrix:

 ---------------------
   m11    m12    m13
   m21    m22    m23
   m31    m32    m33
 ---------------------

Then this is the resulting matrix:

 -------------------------
   m11    m12    m13    0
   m21    m22    m23    0
   m31    m32    m33    0
    0      0      0     1
 -------------------------

matrix44ToMatrix33 :: Matrix44 -> Matrix33 Source

Transforms a Matrix44 into a Matrix33.

If this is the original 4x4 matrix:

 ----------------------------
   m11    m12    m13    m14
   m21    m22    m23    m24
   m31    m32    m33    m34
   m41    m42    m43    m44
 ----------------------------

Then this is the resulting 3x3 matrix:

 ---------------------
   m11    m12    m13
   m21    m22    m23
   m31    m32    m33
 ---------------------

The fourth row and column are discarded.

quaternions

quaternion Source

Arguments

:: Float	The x-component.
-> Float	The y-component.
-> Float	The z-component.
-> Float	The w-component.
-> Quaternion

Construct a quaternion out of 4 values.

identityq :: Quaternion Source

Returns the identity quaternion. It won't rotate anything.

canonicalizeq :: Quaternion -> Quaternion Source

"canonicalizes" a quaternion.

Some rotations have different representations as a quaternion. This function canonicalizes the quaternion so that those rotations are the same.

Don't rely on this. This is used in some automatic tests to see that the quaternions work correctly.

distanceq :: Quaternion -> Quaternion -> Float Source

Returns the Euclidean distance between two quaternions.

lengthq :: Quaternion -> Float Source

Returns the length of a quaternion.

normalizeq :: Quaternion -> Quaternion Source

Normalizes a quaternion to unit length.

multiplyq :: Quaternion -> Quaternion -> Quaternion Source

Multiplies two quaternions together.

zeroq :: Quaternion Source

Returns a quaternion where all the elements are zero.

axisAngleToQuaternion Source

Arguments

:: Float	The angle, in radians.
-> Vector3	The rotation axis.
-> Quaternion

Turns an axis angle rotation into a quaternion.

matrix44ToQuaternion :: Matrix44 -> Quaternion Source

Extracts rotation from a 4x4 matrix and returns it as a quaternion.

Note that

    matrix44ToQuaternion . quaternionToMatrix44

may not be the identity function. The signs on the quaternion components may be different and because the floating point calculation is not completely precise, the values are often slightly different than they were originally.

quaternionToMatrix44 :: Quaternion -> Matrix44 Source

Turns the quaternion into a 4x4 rotation matrix.

toTupleq :: Quaternion -> (Float, Float, Float, Float) Source

Turns a quaternion into a 4-tuple.

fromTupleq :: (Float, Float, Float, Float) -> Quaternion Source

Turns a 4-tuple into a quaternion.

3-component vectors

vector3 Source

Arguments

:: Float	X-coodinate.
-> Float	Y-coodinate.
-> Float	Z-coodinate.
-> Vector3

Constructs a Vector3 out of three values.

zero3 :: Vector3 Source

Returns a vector where all components are 0.

distance3 :: Vector3 -> Vector3 -> Float Source

Returns the Euclidean distance between to 3-vectors.

length3 :: Vector3 -> Float Source

Returns the length of a 3-vector.

plus3 :: Vector3 -> Vector3 -> Vector3 Source

Sums two 3-vectors together.

minus3 :: Vector3 -> Vector3 -> Vector3 Source

Subtracts the second 3-vector from the first.

normalize3 :: Vector3 -> Vector3 Source

Normalizes a 3-vector to unit length.

If the vector is a zero vector then this probably gives you a vector with NaNs as values.

angle3 :: Vector3 -> Vector3 -> Float Source

Returns the angle, in radians, between two 3-vectors.

The vectors are normalized by this function so you need not to do that yourself.

cross3 :: Vector3 -> Vector3 -> Vector3 Source

Returns the cross product between two 3-vectors.

dot3 :: Vector3 -> Vector3 -> Float Source

Returns the dot product between two 3-vectors.

negative3 :: Vector3 -> Vector3 Source

Negates all components of a 3-vector.

scalarMultiply3 :: Float -> Vector3 -> Vector3 Source

Multiplies all components of a 3-vector with a scalar.

vector3_1ToQuaternion :: Vector3 -> Float -> Quaternion Source

Turns a Vector3 and an extra value to a quaternion.

vector3Transform44 :: Matrix44 -> Vector3 -> Vector3 Source

Transforms a 3-vector with a 4x4 matrix.

This would be the same as transforming a 4-vector with a 4x4 matrix but the fourth component is taken to be 1 and is not returned.

toTuple3 :: Vector3 -> (Float, Float, Float) Source

Transforms a 3-vector into a tuple.

fromTuple3 :: (Float, Float, Float) -> Vector3 Source

Transforms a tuple into a 3-vector.

Lenses

_x :: Lens' Vector3 Float Source

_y :: Lens' Vector3 Float Source

_z :: Lens' Vector3 Float Source

Misc

prettyShow :: Matrix44 -> String Source

Returns a "pretty" string that represents a 4x4 matrix.

This could be useful for debugging (and has been used as such in the development of Caramia). The default Show instance for Matrix44 is machine-readable but annoying for humans to read. This function returns a somewhat more human-readable string that you can display.

The string will contain newlines.