Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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 Storable
s.
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.
- data Matrix44 = Matrix44 {}
- data Matrix33 = Matrix33 {}
- data Vector3 = Vector3 {}
- data Quaternion = Quaternion {}
- sizeOfMatrix44 :: Int
- sizeOfMatrix33 :: Int
- sizeOfVector3 :: Int
- sizeOfQuaternion :: Int
- matrix44 :: Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Matrix44
- withMatrix44Ptr :: Matrix44 -> (Ptr CFloat -> IO a) -> IO a
- inverse44 :: Matrix44 -> Matrix44
- identity44 :: Matrix44
- multiply44 :: Matrix44 -> Matrix44 -> Matrix44
- determinant44 :: Matrix44 -> Float
- zero44 :: Matrix44
- perspective44 :: Float -> Float -> Float -> Float -> Matrix44
- distance44 :: Matrix44 -> Matrix44 -> Float
- frustum44 :: Float -> Float -> Float -> Float -> Float -> Float -> Matrix44
- ortho44 :: Float -> Float -> Float -> Float -> Float -> Float -> Matrix44
- lookat44 :: Vector3 -> Vector3 -> Vector3 -> Matrix44
- translate44 :: Vector3 -> Matrix44 -> Matrix44
- transpose44 :: Matrix44 -> Matrix44
- scale44 :: Vector3 -> Matrix44 -> Matrix44
- rotate44 :: Float -> Vector3 -> Matrix44 -> Matrix44
- matrix33 :: Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Matrix33
- withMatrix33Ptr :: Matrix33 -> (Ptr CFloat -> IO a) -> IO a
- inverse33 :: Matrix33 -> Matrix33
- identity33 :: Matrix33
- multiply33 :: Matrix33 -> Matrix33 -> Matrix33
- determinant33 :: Matrix33 -> Float
- zero33 :: Matrix33
- distance33 :: Matrix33 -> Matrix33 -> Float
- transpose33 :: Matrix33 -> Matrix33
- matrix33ToMatrix44 :: Matrix33 -> Matrix44
- matrix44ToMatrix33 :: Matrix44 -> Matrix33
- quaternion :: Float -> Float -> Float -> Float -> Quaternion
- identityq :: Quaternion
- canonicalizeq :: Quaternion -> Quaternion
- distanceq :: Quaternion -> Quaternion -> Float
- lengthq :: Quaternion -> Float
- normalizeq :: Quaternion -> Quaternion
- multiplyq :: Quaternion -> Quaternion -> Quaternion
- zeroq :: Quaternion
- axisAngleToQuaternion :: Float -> Vector3 -> Quaternion
- matrix44ToQuaternion :: Matrix44 -> Quaternion
- quaternionToMatrix44 :: Quaternion -> Matrix44
- toTupleq :: Quaternion -> (Float, Float, Float, Float)
- fromTupleq :: (Float, Float, Float, Float) -> Quaternion
- vector3 :: Float -> Float -> Float -> Vector3
- zero3 :: Vector3
- distance3 :: Vector3 -> Vector3 -> Float
- length3 :: Vector3 -> Float
- plus3 :: Vector3 -> Vector3 -> Vector3
- minus3 :: Vector3 -> Vector3 -> Vector3
- normalize3 :: Vector3 -> Vector3
- angle3 :: Vector3 -> Vector3 -> Float
- cross3 :: Vector3 -> Vector3 -> Vector3
- dot3 :: Vector3 -> Vector3 -> Float
- negative3 :: Vector3 -> Vector3
- scalarMultiply3 :: Float -> Vector3 -> Vector3
- vector3_1ToQuaternion :: Vector3 -> Float -> Quaternion
- vector3Transform44 :: Matrix44 -> Vector3 -> Vector3
- toTuple3 :: Vector3 -> (Float, Float, Float)
- fromTuple3 :: (Float, Float, Float) -> Vector3
- _x :: Lens' Vector3 Float
- _y :: Lens' Vector3 Float
- _z :: Lens' Vector3 Float
- prettyShow :: Matrix44 -> String
Documentation
A 4x4 matrix. Each mXX function accesses an individual element of the matrix.
A 3x3 matrix. Each nXX function accesses an individual element of the matrix.
data Quaternion Source
sizeOfs
Returns the size of a Matrix4
. This is just a shortcut to calling
sizeOf
on a matrix.
Returns the size of a Matrix3
. This is just a shortcut to calling
sizeOf
on a matrix.
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 ...
:: 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.
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.
:: 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.
:: 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.
:: 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.
:: 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.
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.
Modify a 4x4 matrix to scale everything by given vector.
:: 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.
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.
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.
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
:: 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.
Returns a quaternion where all the elements are zero.
:: 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.
fromTupleq :: (Float, Float, Float, Float) -> Quaternion Source
Turns a 4-tuple into a quaternion.
3-component vectors
Constructs a Vector3
out of three values.
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.
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.
Lenses
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.