matrixlib.h

   1
   2 #ifndef MATRIXLIB_H
   3 #define MATRIXLIB_H
   4
   5 #ifndef M_PI
   6 #define M_PI            3.14159265358979323846  // matches value in gcc v2 math.h
   7 #endif
   8
   9 //#define MATRIX4x4_OPENGLORIENTATION
  10
  11 typedef struct matrix4x4_s
  12 {
  13         vec_t m[4][4];
  14 }
  15 matrix4x4_t;
  16
  17 extern const matrix4x4_t identitymatrix;
  18
  19 // functions for manipulating 4x4 matrices
  20
  21 // copy a matrix4x4
  22 void Matrix4x4_Copy (matrix4x4_t *out, const matrix4x4_t *in);
  23 // copy only the rotation portion of a matrix4x4
  24 void Matrix4x4_CopyRotateOnly (matrix4x4_t *out, const matrix4x4_t *in);
  25 // copy only the translate portion of a matrix4x4
  26 void Matrix4x4_CopyTranslateOnly (matrix4x4_t *out, const matrix4x4_t *in);
  27 // multiply two matrix4x4 together, combining their transformations
  28 // (warning: order matters - Concat(a, b, c) != Concat(a, c, b))
  29 void Matrix4x4_Concat (matrix4x4_t *out, const matrix4x4_t *in1, const matrix4x4_t *in2);
  30 // swaps the rows and columns of the matrix
  31 // (is this useful for anything?)
  32 void Matrix4x4_Transpose (matrix4x4_t *out, const matrix4x4_t *in1);
  33 // creates a matrix that does the opposite of the matrix provided
  34 // this is a full matrix inverter, it should be able to invert any matrix that
  35 // is possible to invert
  36 // (non-uniform scaling, rotation, shearing, and translation, possibly others)
  37 // warning: this function is SLOW
  38 int Matrix4x4_Invert_Full (matrix4x4_t *out, const matrix4x4_t *in1);
  39 // creates a matrix that does the opposite of the matrix provided
  40 // only supports translate, rotate, scale (not scale3) matrices
  41 void Matrix4x4_Invert_Simple (matrix4x4_t *out, const matrix4x4_t *in1);
  42 // blends between two matrices, used primarily for animation interpolation
  43 // (note: it is recommended to follow this with Matrix4x4_Normalize, a method
  44 //  known as nlerp rotation, often better for animation purposes than slerp)
  45 void Matrix4x4_Interpolate (matrix4x4_t *out, matrix4x4_t *in1, matrix4x4_t *in2, double frac);
  46 // zeros all matrix components, used with Matrix4x4_Accumulate
  47 void Matrix4x4_Clear (matrix4x4_t *out);
  48 // adds a weighted contribution from the supplied matrix, used to blend 3 or
  49 // more matrices with weighting, it is recommended that Matrix4x4_Normalize be
  50 // called afterward (a method known as nlerp rotation, often better for
  51 // animation purposes than slerp)
  52 void Matrix4x4_Accumulate (matrix4x4_t *out, matrix4x4_t *in, double weight);
  53 // creates a matrix that does the same rotation and translation as the matrix
  54 // provided, but no uniform scaling, does not support scale3 matrices
  55 void Matrix4x4_Normalize (matrix4x4_t *out, matrix4x4_t *in1);
  56 // creates a matrix with vectors normalized individually (use after
  57 // Matrix4x4_Accumulate)
  58 void Matrix4x4_Normalize3 (matrix4x4_t *out, matrix4x4_t *in1);
  59 // modifies a matrix to have all vectors and origin reflected across the plane
  60 // to the opposite side (at least if axisscale is -2)
  61 void Matrix4x4_Reflect (matrix4x4_t *out, double normalx, double normaly, double normalz, double dist, double axisscale);
  62
  63 // creates an identity matrix
  64 // (a matrix which does nothing)
  65 void Matrix4x4_CreateIdentity (matrix4x4_t *out);
  66 // creates a translate matrix
  67 // (moves vectors)
  68 void Matrix4x4_CreateTranslate (matrix4x4_t *out, double x, double y, double z);
  69 // creates a rotate matrix
  70 // (rotates vectors)
  71 void Matrix4x4_CreateRotate (matrix4x4_t *out, double angle, double x, double y, double z);
  72 // creates a scaling matrix
  73 // (expands or contracts vectors)
  74 // (warning: do not apply this kind of matrix to direction vectors)
  75 void Matrix4x4_CreateScale (matrix4x4_t *out, double x);
  76 // creates a squishing matrix
  77 // (expands or contracts vectors differently in different axis)
  78 // (warning: this is not reversed by Invert_Simple)
  79 // (warning: do not apply this kind of matrix to direction vectors)
  80 void Matrix4x4_CreateScale3 (matrix4x4_t *out, double x, double y, double z);
  81 // creates a matrix for a quake entity
  82 void Matrix4x4_CreateFromQuakeEntity(matrix4x4_t *out, double x, double y, double z, double pitch, double yaw, double roll, double scale);
  83 // creates a duke3d view matrix for a quake view matrix ;)
  84 void Matrix4x4_QuakeToDuke3D(const matrix4x4_t *in, matrix4x4_t *out, double maxShearAngle);
  85
  86 // converts a matrix4x4 to a set of 3D vectors for the 3 axial directions, and the translate
  87 void Matrix4x4_ToVectors(const matrix4x4_t *in, vec_t vx[3], vec_t vy[3], vec_t vz[3], vec_t t[3]);
  88 // creates a matrix4x4 from a set of 3D vectors for axial directions, and translate
  89 void Matrix4x4_FromVectors(matrix4x4_t *out, const vec_t vx[3], const vec_t vy[3], const vec_t vz[3], const vec_t t[3]);
  90
  91 // converts a matrix4x4 to a double[16] array in the OpenGL orientation
  92 void Matrix4x4_ToArrayDoubleGL(const matrix4x4_t *in, double out[16]);
  93 // creates a matrix4x4 from a double[16] array in the OpenGL orientation
  94 void Matrix4x4_FromArrayDoubleGL(matrix4x4_t *out, const double in[16]);
  95 // converts a matrix4x4 to a double[16] array in the Direct3D orientation
  96 void Matrix4x4_ToArrayDoubleD3D(const matrix4x4_t *in, double out[16]);
  97 // creates a matrix4x4 from a double[16] array in the Direct3D orientation
  98 void Matrix4x4_FromArrayDoubleD3D(matrix4x4_t *out, const double in[16]);
  99
 100 // converts a matrix4x4 to a float[16] array in the OpenGL orientation
 101 void Matrix4x4_ToArrayFloatGL(const matrix4x4_t *in, float out[16]);
 102 // creates a matrix4x4 from a float[16] array in the OpenGL orientation
 103 void Matrix4x4_FromArrayFloatGL(matrix4x4_t *out, const float in[16]);
 104 // converts a matrix4x4 to a float[16] array in the Direct3D orientation
 105 void Matrix4x4_ToArrayFloatD3D(const matrix4x4_t *in, float out[16]);
 106 // creates a matrix4x4 from a float[16] array in the Direct3D orientation
 107 void Matrix4x4_FromArrayFloatD3D(matrix4x4_t *out, const float in[16]);
 108
 109 // converts a matrix4x4 to a float[12] array in the OpenGL orientation
 110 void Matrix4x4_ToArray12FloatGL(const matrix4x4_t *in, float out[12]);
 111 // creates a matrix4x4 from a float[12] array in the OpenGL orientation
 112 void Matrix4x4_FromArray12FloatGL(matrix4x4_t *out, const float in[12]);
 113 // converts a matrix4x4 to a float[12] array in the Direct3D orientation
 114 void Matrix4x4_ToArray12FloatD3D(const matrix4x4_t *in, float out[12]);
 115 // creates a matrix4x4 from a float[12] array in the Direct3D orientation
 116 void Matrix4x4_FromArray12FloatD3D(matrix4x4_t *out, const float in[12]);
 117
 118 // creates a matrix4x4 from an origin and quaternion (used mostly with skeletal model formats such as PSK)
 119 void Matrix4x4_FromOriginQuat(matrix4x4_t *m, double ox, double oy, double oz, double x, double y, double z, double w);
 120 // creates an origin and quaternion from a matrix4x4_t, quat[3] is always positive
 121 void Matrix4x4_ToOrigin3Quat4Float(const matrix4x4_t *m, float *origin, float *quat);
 122 // creates a matrix4x4 from an origin and canonical unit-length quaternion (used mostly with skeletal model formats such as MD5)
 123 void Matrix4x4_FromDoom3Joint(matrix4x4_t *m, double ox, double oy, double oz, double x, double y, double z);
 124
 125 // creates a matrix4x4_t from an origin and canonical unit-length quaternion in short[7] normalized format
 126 void Matrix4x4_FromBonePose7s(matrix4x4_t *m, float originscale, const short *pose7s);
 127 // creates a short[7] representation from normalized matrix4x4_t
 128 void Matrix4x4_ToBonePose7s(const matrix4x4_t *m, float origininvscale, short *pose7s);
 129
 130 // blends two matrices together, at a given percentage (blend controls percentage of in2)
 131 void Matrix4x4_Blend (matrix4x4_t *out, const matrix4x4_t *in1, const matrix4x4_t *in2, double blend);
 132
 133 // transforms a 3D vector through a matrix4x4
 134 void Matrix4x4_Transform (const matrix4x4_t *in, const vec_t v[3], vec_t out[3]);
 135 // transforms a 4D vector through a matrix4x4
 136 // (warning: if you don't know why you would need this, you don't need it)
 137 // (warning: the 4th component of the vector should be 1.0)
 138 void Matrix4x4_Transform4 (const matrix4x4_t *in, const vec_t v[4], vec_t out[4]);
 139 // reverse transforms a 3D vector through a matrix4x4, at least for *simple*
 140 // cases (rotation and translation *ONLY*), this attempts to undo the results
 141 // of Transform
 142 //void Matrix4x4_SimpleUntransform (const matrix4x4_t *in, const vec_t v[3], vec_t out[3]);
 143 // transforms a direction vector through the rotation part of a matrix
 144 void Matrix4x4_Transform3x3 (const matrix4x4_t *in, const vec_t v[3], vec_t out[3]);
 145 // transforms a positive distance plane (A*x+B*y+C*z-D=0) through a rotation or translation matrix
 146 void Matrix4x4_TransformPositivePlane (const matrix4x4_t *in, vec_t x, vec_t y, vec_t z, vec_t d, vec_t *o);
 147 // transforms a standard plane (A*x+B*y+C*z+D=0) through a rotation or translation matrix
 148 void Matrix4x4_TransformStandardPlane (const matrix4x4_t *in, vec_t x, vec_t y, vec_t z, vec_t d, vec_t *o);
 149
 150 // ease of use functions
 151 // immediately applies a Translate to the matrix
 152 void Matrix4x4_ConcatTranslate (matrix4x4_t *out, double x, double y, double z);
 153 // immediately applies a Rotate to the matrix
 154 void Matrix4x4_ConcatRotate (matrix4x4_t *out, double angle, double x, double y, double z);
 155 // immediately applies a Scale to the matrix
 156 void Matrix4x4_ConcatScale (matrix4x4_t *out, double x);
 157 // immediately applies a Scale3 to the matrix
 158 void Matrix4x4_ConcatScale3 (matrix4x4_t *out, double x, double y, double z);
 159
 160 // extracts origin vector (translate) from matrix
 161 void Matrix4x4_OriginFromMatrix (const matrix4x4_t *in, vec_t *out);
 162 // extracts scaling factor from matrix (only works for uniform scaling)
 163 double Matrix4x4_ScaleFromMatrix (const matrix4x4_t *in);
 164
 165 // replaces origin vector (translate) in matrix
 166 void Matrix4x4_SetOrigin (matrix4x4_t *out, double x, double y, double z);
 167 // moves origin vector (translate) in matrix by a simple translate
 168 void Matrix4x4_AdjustOrigin (matrix4x4_t *out, double x, double y, double z);
 169 // scales vectors of a matrix in place and allows you to scale origin as well
 170 void Matrix4x4_Scale (matrix4x4_t *out, double rotatescale, double originscale);
 171 // ensures each element of the 3x3 rotation matrix is facing in the + direction
 172 void Matrix4x4_Abs (matrix4x4_t *out);
 173
 174 #endif