GL Studio Safety Critical Embedded C++ Runtime Library
gls_matrix_affine_double.h
Go to the documentation of this file.
1 #ifndef _GLS_MATRIXAFFINE_DOUBLE_H
2 #define _GLS_MATRIXAFFINE_DOUBLE_H
3 
4 /*! \file gls_matrix_affine_double.h
5 \brief This header defines The GlsMatrixAffineD class for use in
6  the GL Studio DO-178B Runtime Library.
7 
8 \par Copyright Information
9 Copyright (C) 1999-2012 The DiSTI Corporation<br>
10 Orlando, FL USA<br>
11 All rights reserved.<br>
12 
13  This file is copyrighted software and contains proprietary trade secrets of
14 DiSTI, and embodies substantial creative efforts as well as confidential
15 information, ideas, and expressions.
16 
17  Permission to use, and copy this software and its documentation for any
18 purpose is hereby granted per the Distribution Agreement and/or the Licensing
19 Agreement signed with DiSTI. This permission is granted provided that:
20  1. The above copyright notice appears in all copies.
21  2. That both the copyright notice and this permission notice appear in
22  the supporting documentation.
23  3. That the names DiSTI and GL Studio not be used in advertising or
24  publicity pertaining to distribution of the software without specific,
25  written prior permission of DiSTI.
26 
27  Permission to modify the software is granted, but not the right to
28 distribute the source code whether modified, or non-modified. Modifying the
29 software might invalidate the DO-178B certification package.
30 
31  Permission to distribute binaries produced by compiling source code, or
32 modified source code is granted, provided you:
33  1. Provide your name and address as the primary contact for the support
34  of your modified version.
35  2. Retain our contact information in regard to use of the base software.
36 
37  DiSTI does not provide warranty for this software or guarantee that it
38 satisfies any specification or requirement unless otherwise stated in a
39 specific contractual arrangement between the customer and DiSTI.
40 
41 */
42 
43 #include "gls_include.h"
44 #include "gls_types.h"
45 #include "gls_vertex.h"
46 #include "gls_class_invariant.h"
47 
48 /** 4x4 affine transformation matrix. It provides the ability to perform rotations,
49  * and translations. Results are cumulative, i.e. every rotate
50  * and translate call transforms the terms that already exist in the matrix.
51  * \invariant _matrix column array points to _data array,
52  * each element of the data array is a valid floating point value
53  */
55 {
56 public:
58 
59  static const GlsUInt32 DIMENSION = 4u; /**< matrix is DIMENSION x DIMENSION */
60  typedef GlsFloat64 CStyleMatrix[ DIMENSION ][ DIMENSION ]; /**< C style matrix representation */
61 
62  /** affine matrix of floats in format suitable for GL */
63  typedef GLfloat GLMatrixAffineF[ DIMENSION * DIMENSION ];
64  /** identity GLMatrixAffineF matrix ( column major ) */
66 
67  /** enumeration describing axes of rotation */
69  {
70  ROTATION_AXIS_X, /**< X axis */
71  ROTATION_AXIS_Y, /**< Y axis */
72  ROTATION_AXIS_Z, /**< Z axis */
73 
74  #if defined( GLS_DEBUG )
75  ROTATION_AXIS_INVALID /**< invalid rotation axis ( GLS_DEBUG only )*/
76  #endif // GLS_DEBUG
77  };
78 
79  /** Default constructor. The new matrix will be the identity matrix.
80  * \pre none
81  * \post object created, matrix is identity matrix
82  */
83  GlsMatrixAffineD( void );
84 
85  /** Copy Constructor.
86  * \param m matrix to copy.
87  * \pre none
88  * \post matrix is equal to m
89  */
91 
92  /** Constructor - initialize from a CStyleMatrix
93  * \param m c style matrix with intial matrix values
94  * \pre GlsMatrixAffineDCStyleMatrixIsValid( m )
95  * \post instance created, matrix is equal to m
96  */
97  GlsMatrixAffineD( const CStyleMatrix &m );
98 
99  /** Destructor - destroy instance
100  * \pre none
101  * \post instance destroyed
102  */
104 
105  /** copy given matrix
106  * \param m matrix in question
107  * \pre none
108  * \post matrix elements are equal to matrix elements of m
109  */
110  void SetMatrix( const GlsMatrixAffineD &m );
111 
112  /** Set the element in the matrix at the given row and column
113  * \param row zero based row of element ( < DIMENSION )
114  * \param col zero based column of element ( < DIMENSION )
115  * \param val new value for element
116  * \pre row < DIMENSION, col < DIMENSION,
117  * GlsFloatIsValid( val )
118  * \post element at row and column is set to new value
119  */
120  void SetElement( const GlsUInt32 row, const GlsUInt32 col, const GlsFloat64 val );
121 
122  /** Get the element in the matrix at the given row and column
123  * \param row zero based row of element ( < DIMENSION )
124  * \param col zero based column of element ( < DIMENSION )
125  * \return element at given row and column
126  * \pre row < DIMENSION, col < DIMENSION
127  * \post none
128  */
129  GlsFloat64 GetElement( const GlsUInt32 row, const GlsUInt32 col ) const;
130 
131  /** Multiply this matrix by m where this matrix is on the left side and
132  * and m is on the right side of the multiplication,
133  * ( *this = (*this) * m )
134  * \param m matrix to multiply by
135  * \pre none
136  * \post this matrix is multiplied by m ( *this * m )
137  */
138  void LeftMultiply( const GlsMatrixAffineD &m );
139 
140  /** Multiply this matrix by m where this matrix is on the right side and
141  * and m is on the left side of the multiplication,
142  * ( *this = m * (*this) )
143  * \param m matrix to multiply by
144  * \pre none
145  * \post this matrix is multiplied by m ( m * *this )
146  */
147  void RightMultiply( const GlsMatrixAffineD &m );
148 
149  /** Perform a rotation transformation around a major axis around the origin,
150  * and combine this transformation with the existing matrix data.
151  * \param angle rotation angle in degrees
152  * \param rotationAxis major axis of rotation
153  * \pre GlsFloatIsValid( angle ),
154  * GlsMatrixAffineDRotationAxisIsValid( rotationAxis )
155  * \post matrix is rotation transformed
156  */
157  void Rotate( const GlsFloat64 angle, const RotationAxis rotationAxis );
158 
159  /** Perform a translation using the given 3D vector and combine with this matrix
160  * \param v 3D vector in question
161  * \pre v.IsValid()
162  * \post matrix is translated by v
163  */
164  void Translate( const GlsVector3D &v );
165 
166  /** populate the given GLMatrixAffineF with the values of the matrix
167  * \param dst [out] gets values of the matrix
168  * \pre none
169  * \post dst contains values of the matrix
170  */
171  void PopulateGLMatrixAffineF( GLMatrixAffineF &dst ) const;
172 
173  /** Determine if the given c style matrix is the identity matrix
174  * \param m c style matrix in question
175  * \return GLS_TRUE if identity else GLS_FALSE
176  * \pre GlsMatrixAffineDCStyleMatrixIsValid( m )
177  * \post none
178  */
179  static GlsBool CStyleMatrixIsIdentity( const CStyleMatrix &m );
180 
181  /** Determine if the given GL matrix is identity
182  * \param m matrix in question
183  * \return GLS_TRUE if , is identity else GLS_FALSE
184  * \pre GLMatrixAffineFIsValid( m )
185  * \post none
186  */
188 
189  /** Copy a GLMatrixAffineF
190  * \param dst [out] destination GLMatrixAffineF
191  * \param src source GLMatrixAffineF
192  * \pre GLMatrixAffineFIsValid( src )
193  * \post dst is a copy of src
194  */
195  static void CopyGLMatrixAffineF( GLMatrixAffineF &dst, const GLMatrixAffineF &src );
196 
197  /** Multiply the given 3D homogeneous vector by the given GL matrix
198  * \param m GL matrix in question
199  * \param v 3D homogeneous vector in question
200  * \param dst [out] receives result ( m * v )
201  * \pre GLMatrixAffineFIsValid( m ), v.IsValid()
202  * \post dst = m * v
203  */
204  static void VectorMultGLMatrixAffineF( const GLMatrixAffineF &m, const GlsHomogeneousVector3D &v,
205  GlsHomogeneousVector3D &dst );
206 
207  /** Multiply two GL matrices ( lhs, rhs ) and store in result
208  * result = ( lhs * rhs )
209  * \param lhs left hand side of multiplication
210  * \param rhs right hand side of multiplication
211  * \param result [out] gets resultant matrix form multiplication
212  * \pre GLMatrixAffineFIsValid( lhs ), GLMatrixAffineFIsValid( rhs )
213  * \post result = ( lhs * rhs )
214  */
215  static void MatrixMultGLMatrixAffineF( const GLMatrixAffineF &lhs, const GLMatrixAffineF &rhs,
216  GLMatrixAffineF &result );
217 
218 protected:
219  /** identity c style matrix */
221  /** identity matrix in data representation format */
223 
224  /** This is the actual matrix data stored in column-major ordering in
225  * a one-dimensional array of the appropriate size to store all matrix
226  * terms. The data is stored in this manner so that it can be passed
227  * to OpenGL matrix operations, which expect matrices to be ordered
228  * this way.
229  */
231 
232  /** A column index array. Each element in this array "points"
233  * to a column of the matrix within the above data. By using this index,
234  * we can address matrix terms using two dimensions, column and row,
235  * without incurring a multiplication. Eg. matrix[0] points to a column
236  * within data, which is the address of the first term in the column.
237  * We can further address into the column and access a particular row
238  * by adding another dimension, eg. matrix[0][1]. The indices must
239  * be set up at construction time.
240  */
242 
243  /** This should be called from all constructors, as it initializes the
244  * matrix column index so that matrix elements can be addressed in two
245  * dimensions, but a multiplication is not incurred when doing so.
246  * \pre none
247  * \post _matrix elements are initialized
248  */
249  void Initialize( void );
250 
251  /** Set this matrix to the identity matrix. The identity matrix is
252  * I = [Aij], where Aii = 1 and Aij = 0 for i != j. Thus, for the identity
253  * matrix, the terms off the main diagonal are all zero, and the terms on
254  * the main diagonal are all one.
255  * \pre none
256  * \post matrix is identity matrix
257  */
258  void MakeIdentity( void );
259 
260  /** Multiply the two matrices ( lhs, rhs ) and store in result
261  * ( result = ( lhs * rhs )
262  * \param lhs left hand side of multiplication
263  * \param rhs right hand side of multiplication
264  * \param result [out] gets resultant matrix for multiplication
265  * \pre none
266  * \post result = ( lhs * rhs )
267  */
268  void Multiply( const GlsMatrixAffineD &lhs, const GlsMatrixAffineD &rhs, GlsMatrixAffineD &result ) const;
269 
270 private:
271  // Disable implicit generated Members
272  GlsMatrixAffineD& operator=( const GlsMatrixAffineD &rhs );
273 };
274 
275 #if defined( GLS_DEBUG )
276 #pragma BullseyeCoverage save off
277 /** Determine if the given c style matrix is valid
278  * \param mat c style matrix in question
279  * \return GLS_TRUE if valid else GLS_FALSE
280  * \pre none
281  * \post none
282  */
283 inline GlsBool GlsMatrixAffineDCStyleMatrixIsValid( const GlsMatrixAffineD::CStyleMatrix &mat )
284 {
285  GlsBool isValid = GLS_TRUE;
286 
287  // ensure all members are valid floats
288  for( GlsUInt32 row = 0u; ( row < GlsMatrixAffineD::DIMENSION ) && isValid; ++row )
289  {
290  for( GlsUInt32 col = 0u; col < GlsMatrixAffineD::DIMENSION; ++col )
291  {
292  isValid = GlsFloatIsValid( mat[ row ][ col ] );
293  if( !isValid )
294  {
295  break;
296  }
297  }
298  }
299 
300  return( isValid );
301 }
302 #pragma BullseyeCoverage restore
303 #endif // GLS_DEBUG
304 
305 #if defined( GLS_DEBUG )
306 #pragma BullseyeCoverage save off
307 /** Determine if the given matrix rotation axis is valid ( GLS_DEBUG only )
308  * \param rotationAxis rotation axis in question
309  * \return GLS_TRUE if valid else GLS_FALSE
310  * \pre none
311  * \post none
312  */
313 inline GlsBool GlsMatrixAffineDRotationAxisIsValid( const GlsMatrixAffineD::RotationAxis rotationAxis )
314 {
315  return( ( GlsMatrixAffineD::ROTATION_AXIS_X == rotationAxis ) ||
316  ( GlsMatrixAffineD::ROTATION_AXIS_Y == rotationAxis ) ||
317  ( GlsMatrixAffineD::ROTATION_AXIS_Z == rotationAxis ) );
318 }
319 #pragma BullseyeCoverage restore
320 #endif // GLS_DEBUG
321 
322 #if defined( GLS_DEBUG )
323 #pragma BullseyeCoverage save off
324 /** Determine if the given GL matrix is valid ( GLS_DEBUG only )
325  * \param m GL matrix in question
326  * \return GLS_TRUE if valid else GLS_FALSE
327  */
328 inline GlsBool GLMatrixAffineFIsValid( const GlsMatrixAffineD::GLMatrixAffineF &m )
329 {
330  GlsBool isValid = GLS_TRUE;
331 
332  for( GlsUInt32 index = 0u; ( index < ( GlsMatrixAffineD::DIMENSION * GlsMatrixAffineD::DIMENSION ) ) && isValid;
333  ++index )
334  {
335  isValid = GlsFloatIsValid( m[ index ] );
336  GlsAssert( isValid );
337  }
338 
339  return( isValid );
340 }
341 #pragma BullseyeCoverage restore
342 #endif // GLS_DEBUG
343 
344 #endif // _GLS_MATRIXAFFINE_DOUBLE_H
void RightMultiply(const GlsMatrixAffineD &m)
Definition: gls_vertex.h:82
bool GlsBool
Definition: gls_types.h:96
#define GlsAssert(_exp)
Definition: gls_assert.h:108
#define GLS_CLASS_INVARIANT_DECLARATION(ClassName)
Definition: gls_class_invariant.h:80
Definition: gls_vertex.h:65
static GlsBool CStyleMatrixIsIdentity(const CStyleMatrix &m)
GlsFloat64 _data[DIMENSION *DIMENSION]
Definition: gls_matrix_affine_double.h:230
static const GlsMatrixAffineD::CStyleMatrix IDENTITY_MATRIX_C_STYLE
Definition: gls_matrix_affine_double.h:220
void MakeIdentity(void)
unsigned int GlsUInt32
Definition: gls_types.h:73
void SetMatrix(const GlsMatrixAffineD &m)
This header defines the basic types used by the GL Studio DO-178B Runtime Library.
This header defines any preprocessor defines needed to configure the GL Studio DO-178B Runtime Librar...
Definition: gls_matrix_affine_double.h:71
GlsFloat64 CStyleMatrix[DIMENSION][DIMENSION]
Definition: gls_matrix_affine_double.h:60
GLfloat GLMatrixAffineF[DIMENSION *DIMENSION]
Definition: gls_matrix_affine_double.h:63
static const GLMatrixAffineF IDENTITY_MATRIX_GL
Definition: gls_matrix_affine_double.h:65
void Translate(const GlsVector3D &v)
static const GlsFloat64 IDENTITY_MATRIX_DATA_REP[DIMENSION *DIMENSION]
Definition: gls_matrix_affine_double.h:222
void SetElement(const GlsUInt32 row, const GlsUInt32 col, const GlsFloat64 val)
void Multiply(const GlsMatrixAffineD &lhs, const GlsMatrixAffineD &rhs, GlsMatrixAffineD &result) const
#define GLS_TRUE
Definition: gls_types.h:99
This header defines a GLS_DEBUG only macro for facilitating evaluating class invariants in the GL Stu...
Definition: gls_matrix_affine_double.h:54
RotationAxis
Definition: gls_matrix_affine_double.h:68
GlsFloat64 * _matrix[DIMENSION]
Definition: gls_matrix_affine_double.h:241
void Initialize(void)
double GlsFloat64
Definition: gls_types.h:87
static void MatrixMultGLMatrixAffineF(const GLMatrixAffineF &lhs, const GLMatrixAffineF &rhs, GLMatrixAffineF &result)
static GlsBool GLMatrixAffineFIsIdentity(const GLMatrixAffineF &m)
void Rotate(const GlsFloat64 angle, const RotationAxis rotationAxis)
Definition: gls_matrix_affine_double.h:70
static const GlsUInt32 DIMENSION
Definition: gls_matrix_affine_double.h:59
static void CopyGLMatrixAffineF(GLMatrixAffineF &dst, const GLMatrixAffineF &src)
This header defines classes for working with 2D and 3D vectors, vertices and textured vertices in the...
Definition: gls_matrix_affine_double.h:72
static void VectorMultGLMatrixAffineF(const GLMatrixAffineF &m, const GlsHomogeneousVector3D &v, GlsHomogeneousVector3D &dst)
void LeftMultiply(const GlsMatrixAffineD &m)
void PopulateGLMatrixAffineF(GLMatrixAffineF &dst) const
GlsFloat64 GetElement(const GlsUInt32 row, const GlsUInt32 col) const