1 /*---------------------------------------------------------------------------*
2 Project: Matrix Vector Library (Structure Version)
3 File: mat44.h
4
5 Copyright (C) Nintendo. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 *---------------------------------------------------------------------------*/
14
15
16 /*---------------------------------------------------------------------------*
17 Matrix-Vector Library : 4x4 Matrix (Structure Version)
18 *---------------------------------------------------------------------------*/
19
20 #ifndef __MAT44_H__
21 #define __MAT44_H__
22
23 #include <cafe/mat.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /// @addtogroup MAT
30 /// @{
31
32 /*---------------------------------------------------------------------------*
33 4x4 GENERAL MATRIX SECTION
34 *---------------------------------------------------------------------------*/
35
36 /// \brief Sets a 4x4 Identity Matrix.
37 ///
38 /// \param m Matrix to set
39 ///
40 /// \par Usage
41 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
42 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
43 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
44 ///
45 /// \donotcall \threadsafe \devonly \enddonotcall
46 ///
MAT44Identity(Mat44 * m)47 static inline void MAT44Identity ( Mat44 *m )
48 { MTX44Identity ( (Mtx44Ptr)(m->mtx) ); }
49
50 /// \brief Copy a 4x4 Matrix.
51 ///
52 /// \note This is safe for src == dst.
53 ///
54 /// \param src Source matrix
55 /// \param dst Destination matrix
56 ///
57 /// \par Usage
58 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
59 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
60 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
61 ///
62 /// \donotcall \threadsafe \devonly \enddonotcall
63 ///
MAT44Copy(const Mat44 * src,Mat44 * dst)64 static inline void MAT44Copy ( const Mat44 *src, Mat44 *dst )
65 { MTX44Copy ( (Mtx44Ptr)(src->mtx), (Mtx44Ptr)(dst->mtx) ); }
66
67 /// \brief Concatenate two 4x4 Matrix.
68 /// The order of operations is:
69 ///
70 /// AB = A x B
71 ///
72 /// \note Safe if ab == a == b.
73 /// \note In the C version, an extra MTXCopy operation occurs if ab == a or
74 /// ab == b.
75 ///
76 /// \param a Left matrix
77 /// \param b Right matrix
78 /// \param ab Destination matrix
79 ///
80 /// \par Usage
81 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
82 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
83 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
84 ///
85 /// \donotcall \threadsafe \devonly \enddonotcall
86 ///
MAT44Concat(const Mat44 * a,const Mat44 * b,Mat44 * ab)87 static inline void MAT44Concat ( const Mat44 *a, const Mat44 *b, Mat44 *ab )
88 { MTX44Concat ( (Mtx44Ptr)(a->mtx), (Mtx44Ptr)(b->mtx), (Mtx44Ptr)(ab->mtx) ); }
89
90 /// \brief Compute a 4x4 transpose matrix.
91 ///
92 /// \param src Source matrix
93 /// \param xPose Destination (transposed) matrix
94 ///
95 /// \note It is ok if src == xPose.
96 ///
97 /// \par Usage
98 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
99 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
100 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
101 ///
102 /// \donotcall \threadsafe \devonly \enddonotcall
103 ///
MAT44Transpose(const Mat44 * src,Mat44 * xPose)104 static inline void MAT44Transpose ( const Mat44 *src, Mat44 *xPose )
105 { MTX44Transpose ( (Mtx44Ptr)(src->mtx), (Mtx44Ptr)(xPose->mtx) ); }
106
107 /// \brief Computes a fast inverse of a 4x4 Matrix.
108 /// Uses the Gauss-Jordan method (with partial pivoting)
109 ///
110 /// \param src Source matrix
111 /// \param inv Destination (inverse) matrix
112 /// \return 0 if src is not invertible, 1 on success.
113 ///
114 /// \note It is ok if src == inv.
115 ///
116 /// \par Usage
117 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
118 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
119 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
120 ///
121 /// \donotcall \threadsafe \devonly \enddonotcall
122 ///
MAT44Inverse(const Mat44 * src,Mat44 * inv)123 static inline u32 MAT44Inverse ( const Mat44 *src, Mat44 *inv )
124 { return MTX44Inverse ( (Mtx44Ptr)(src->mtx), (Mtx44Ptr)(inv->mtx) ); }
125
126 /*-------------------------------------------------------------------------*
127 MODEL MATRIX SECTION
128 *-------------------------------------------------------------------------*/
129
130 /// \brief Sets a translation 4x4 matrix
131 ///
132 /// \param m Matrix to be set
133 /// \param xT x component of translation
134 /// \param yT y component of translation
135 /// \param zT z component of translation
136 ///
137 /// \par Usage
138 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
139 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
140 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
141 ///
142 /// \donotcall \threadsafe \devonly \enddonotcall
143 ///
MAT44Trans(Mat44 * m,f32 xT,f32 yT,f32 zT)144 static inline void MAT44Trans ( Mat44 *m, f32 xT, f32 yT, f32 zT )
145 { MTX44Trans ( (Mtx44Ptr)(m->mtx), xT, yT, zT ); }
146
147 /// \brief Apply a translation to a 4x4 matrix.
148 /// This function is equivalent to \ref MTX44Trans + \ref MTX44Concat.
149 ///
150 /// \note This is safe for the case where src == dst.
151 ///
152 /// \param src Matrix to multiply the translation by
153 /// \param dst Resulting matrix from concatenation
154 /// \param xT x component of translation
155 /// \param yT y component of translation
156 /// \param zT z component of translation
157 ///
158 /// \par Usage
159 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
160 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
161 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
162 ///
163 /// \donotcall \threadsafe \devonly \enddonotcall
164 ///
MAT44TransApply(const Mat44 * src,Mat44 * dst,f32 xT,f32 yT,f32 zT)165 static inline void MAT44TransApply ( const Mat44 *src, Mat44 *dst, f32 xT, f32 yT, f32 zT )
166 { MTX44TransApply ( (Mtx44Ptr)(src->mtx), (Mtx44Ptr)(dst->mtx), xT, yT, zT ); }
167
168 /// \brief Sets a scale 4x4 matrix
169 ///
170 /// \param m Matrix to be set
171 /// \param xS x component of scale
172 /// \param yS y component of scale
173 /// \param zS z component of scale
174 ///
175 /// \par Usage
176 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
177 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
178 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
179 ///
180 /// \donotcall \threadsafe \devonly \enddonotcall
181 ///
MAT44Scale(Mat44 * m,f32 xS,f32 yS,f32 zS)182 static inline void MAT44Scale ( Mat44 *m, f32 xS, f32 yS, f32 zS )
183 { MTX44Scale ( (Mtx44Ptr)(m->mtx), xS, yS, zS ); }
184
185 /// \brief Apply a scale to a 4x4 matrix.
186 /// This function is equivalent to \ref MTX44Scale + \ref MTX44Concat.
187 ///
188 /// \note This is safe for the case where src == dst.
189 ///
190 /// \param src Matrix to multiply the scale by
191 /// \param dst Resulting matrix from concatenation
192 /// \param xS x component of scale
193 /// \param yS y component of scale
194 /// \param zS z component of scale
195 ///
196 /// \par Usage
197 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
198 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
199 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
200 ///
201 /// \donotcall \threadsafe \devonly \enddonotcall
202 ///
MAT44ScaleApply(const Mat44 * src,Mat44 * dst,f32 xS,f32 yS,f32 zS)203 static inline void MAT44ScaleApply ( const Mat44 *src, Mat44 *dst, f32 xS, f32 yS, f32 zS )
204 { MTX44ScaleApply ( (Mtx44Ptr)(src->mtx), (Mtx44Ptr)(dst->mtx), xS, yS, zS ); }
205
206
207 /// \brief Sets a rotation 4x4 matrix about one of the X, Y or Z axes.
208 ///
209 /// \note Counter clockwise rotation is positive.
210 ///
211 /// \param m Matrix to be set
212 /// \param axis Principal axis of rotation. Must be 'X', 'x', 'Y', 'y', 'Z', or 'z'.
213 /// \param rad Rotation angle in radians
214 ///
215 /// \par Usage
216 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
217 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
218 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
219 ///
220 /// \donotcall \threadsafe \devonly \enddonotcall
221 ///
MAT44RotRad(Mat44 * m,char axis,f32 rad)222 static inline void MAT44RotRad ( Mat44 *m, char axis, f32 rad )
223 { MTX44RotRad ( (Mtx44Ptr)(m->mtx), axis, rad ); }
224
225 /// \brief Sets a rotation 4x4 matrix about one of the X, Y, or Z axes from specified trig ratios.
226 ///
227 /// \note Counter clockwise rotation is positive.
228 ///
229 /// \param m Matrix to be set
230 /// \param axis Principal axis of rotation. Must be 'X', 'x', 'Y', 'y', 'Z', or 'z'.
231 /// \param sinA Sine of rotation angle
232 /// \param cosA Cosine of rotation angle
233 ///
234 /// \par Usage
235 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
236 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
237 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
238 ///
239 /// \donotcall \threadsafe \devonly \enddonotcall
240 ///
MAT44RotTrig(Mat44 * m,char axis,f32 sinA,f32 cosA)241 static inline void MAT44RotTrig ( Mat44 *m, char axis, f32 sinA, f32 cosA )
242 { MTX44RotTrig ( (Mtx44Ptr)(m->mtx), axis, sinA, cosA ); }
243
244 /// \brief Sets a rotation 4x4 matrix about an arbitrary axis.
245 ///
246 /// \note Counter clockwise rotation is positive.
247 ///
248 /// \param m Matrix to be set
249 /// \param axis Pointer to a vector containing the (x, y, z) axis components
250 /// \param rad Rotation angle in radians
251 ///
252 /// \par Usage
253 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
254 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
255 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
256 ///
257 /// \donotcall \threadsafe \devonly \enddonotcall
258 ///
MAT44RotAxisRad(Mat44 * m,const Vec * axis,f32 rad)259 static inline void MAT44RotAxisRad ( Mat44 *m, const Vec *axis, f32 rad)
260 { MTX44RotAxisRad ( (Mtx44Ptr)(m->mtx), axis, rad); }
261
262 /*-------------------------------------------------------------------------*
263 MATRIX-VECTOR SECTION
264 *-------------------------------------------------------------------------*/
265
266 /// \brief Multiplies a vector by a 4x4 matrix
267 ///
268 /// dst = m x src
269 ///
270 /// \note It is safe for src == dst.
271 ///
272 /// \param m Matrix to multiply by
273 /// \param src Source vector of multiply
274 /// \param dst Resulting vector from multiply
275 ///
276 /// \par Usage
277 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
278 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
279 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
280 ///
281 /// \donotcall \threadsafe \devonly \enddonotcall
282 ///
MAT44MultVec(const Mat44 * m,const Vec * src,Vec * dst)283 static inline void MAT44MultVec ( const Mat44 *m, const Vec *src, Vec *dst )
284 { MTX44MultVec ( (Mtx44Ptr)(m->mtx), src, dst ); }
285
286 /// \brief Multiplies an array of vectors by a 4x4 matrix.
287 ///
288 /// \note It is safe for srcBase == dstBase.
289 ///
290 /// \warning This function cannot check for array overflow.
291 ///
292 /// \param m Matrix to multiply by
293 /// \param srcBase Source vector array
294 /// \param dstBase Resulting vector array
295 /// \param count Number of vectors in srcBase and dstBase arrays.
296 ///
297 ///
298 /// \par Usage
299 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
300 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
301 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
302 ///
303 /// \donotcall \threadsafe \devonly \enddonotcall
304 ///
MAT44MultVecArray(const Mat44 * m,const Vec * srcBase,Vec * dstBase,u32 count)305 static inline void MAT44MultVecArray ( const Mat44 *m, const Vec *srcBase, Vec *dstBase, u32 count )
306 { MTX44MultVecArray ( (Mtx44Ptr)(m->mtx), srcBase, dstBase, count ); }
307
308 /// \brief Multiply a vector by a 4x4 Scaling and Rotating matrix
309 /// \note It is assumed that the 4th row/column are (0, 0, 0, 1).
310 ///
311 /// This is equivalent to:
312 ///
313 /// dst = m x src
314 ///
315 /// \note It is safe for src == dst.
316 ///
317 /// \param m Matrix to multiply by
318 /// \param src Source vector for multiply
319 /// \param dst Resulting vector from multiply
320 ///
321 /// \par Usage
322 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
323 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
324 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
325 ///
326 /// \donotcall \threadsafe \devonly \enddonotcall
327 ///
MAT44MultVecSR(const Mat44 * m,const Vec * src,Vec * dst)328 static inline void MAT44MultVecSR ( const Mat44 *m, const Vec *src, Vec *dst )
329 { MTX44MultVecSR ( (Mtx44Ptr)(m->mtx), src, dst ); }
330
331 /// \brief Multiply an array of vector by a 4x4 Scaling and Rotating matrix
332 /// \note It is assumed that the 4th row/column are (0, 0, 0, 1).
333 ///
334 /// This is equivalent to:
335 ///
336 /// dstBase[i] = m x srcBase[i]
337 ///
338 /// \note It is safe for srcBase == dstBase.
339 ///
340 /// \warning This function cannot check for array overflow
341 ///
342 /// \param m Matrix to multiply by
343 /// \param srcBase Source vector array
344 /// \param dstBase Resulting vector array
345 /// \param count Number of vectors in srcBase and dstBase
346 ///
347 ///
348 /// \par Usage
349 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
350 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
351 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
352 ///
353 /// \donotcall \threadsafe \devonly \enddonotcall
354 ///
MAT44MultVecArraySR(const Mat44 * m,const Vec * srcBase,Vec * dstBase,u32 count)355 static inline void MAT44MultVecArraySR ( const Mat44 *m, const Vec *srcBase, Vec *dstBase, u32 count )
356 { MTX44MultVecArraySR ( (Mtx44Ptr)(m->mtx), srcBase, dstBase, count ); }
357
358 /*---------------------------------------------------------------------------*
359 MATRIX CONVERSION
360 *---------------------------------------------------------------------------*/
361
362 /// \brief Convert a 3x4 matrix to a 4x4 matrix.
363 /// The fourth row is set to (0, 0, 0, 1).
364 ///
365 /// \param src Source 3x4 matrix
366 /// \param dst Destination 4x4 matrix
367 ///
368 /// \par Usage
369 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version
370 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version
371 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging.
372 ///
373 /// \donotcall \threadsafe \devonly \enddonotcall
374 ///
MAT34To44(const Mat34 * src,Mat44 * dst)375 static inline void MAT34To44( const Mat34 *src, Mat44 *dst )
376 { MTX34To44( (MtxPtr)(src->mtx), (Mtx44Ptr)(dst->mtx) ); }
377
378 /// @}
379
380 #ifdef __cplusplus
381 }
382 #endif
383
384 #endif // __MAT44_H__
385
386 /*===========================================================================*/
387