gls_matrix_affine_double.h

Go to the documentation of this file.

#ifndef _GLS_MATRIXAFFINE_DOUBLE_H
#define _GLS_MATRIXAFFINE_DOUBLE_H

/*! \file gls_matrix_affine_double.h
\brief  This header defines The GlsMatrixAffineD class for use in
        the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_types.h"
#include "gls_vertex.h"
#include "gls_class_invariant.h"

/** 4x4 affine transformation matrix. It provides the ability to perform rotations,
  * and translations. Results are cumulative, i.e. every rotate
  * and translate call transforms the terms that already exist in the matrix. 
  * \invariant _matrix column array points to _data array,
  *            each element of the data array is a valid floating point value
  */
class GlsMatrixAffineD
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsMatrixAffineD )

    static const GlsUInt32 DIMENSION = 4u;                      /**< matrix is DIMENSION x DIMENSION */
    typedef GlsFloat64 CStyleMatrix[ DIMENSION ][ DIMENSION ];  /**< C style matrix representation */

    /** affine matrix of floats in format suitable for GL */
    typedef GLfloat GLMatrixAffineF[ DIMENSION * DIMENSION ];
    /** identity GLMatrixAffineF matrix ( column major ) */
    static const GLMatrixAffineF IDENTITY_MATRIX_GL;

    /** enumeration describing axes of rotation */
    enum RotationAxis
    {
        ROTATION_AXIS_X,    /**< X axis */
        ROTATION_AXIS_Y,    /**< Y axis */
        ROTATION_AXIS_Z,    /**< Z axis */

        #if defined( GLS_DEBUG )
            ROTATION_AXIS_INVALID   /**< invalid rotation axis ( GLS_DEBUG only )*/
        #endif // GLS_DEBUG
    };

    /** Default constructor. The new matrix will be the identity matrix.
      * \pre none
      * \post object created, matrix is identity matrix
      */
    GlsMatrixAffineD( void );

   /** Copy Constructor.
     * \param m  matrix to copy. 
     * \pre none
     * \post matrix is equal to m
     */
    GlsMatrixAffineD( const GlsMatrixAffineD &m );

    /** Constructor - initialize from a CStyleMatrix 
      * \param m c style matrix with intial matrix values
      * \pre GlsMatrixAffineDCStyleMatrixIsValid( m )
      * \post instance created, matrix is equal to m
      */
    GlsMatrixAffineD( const CStyleMatrix &m );

    /** Destructor - destroy instance
      * \pre none
      * \post instance destroyed
      */
    ~GlsMatrixAffineD();

    /** copy given matrix
      * \param m matrix in question
      * \pre none
      * \post matrix elements are equal to matrix elements of m
      */
    void SetMatrix( const GlsMatrixAffineD &m );

    /** Set the element in the matrix at the given row and column
      * \param row zero based row of element ( < DIMENSION )
      * \param col zero based column of element ( < DIMENSION )
      * \param val new value for element
      * \pre row < DIMENSION, col < DIMENSION,
      *      GlsFloatIsValid( val )
      * \post element at row and column is set to new value
      */
    void SetElement( const GlsUInt32 row, const GlsUInt32 col, const GlsFloat64 val );

    /** Get the element in the matrix at the given row and column
      * \param row zero based row of element ( < DIMENSION )
      * \param col zero based column of element ( < DIMENSION )
      * \return element at given row and column
      * \pre row < DIMENSION, col < DIMENSION
      * \post none
      */
    GlsFloat64 GetElement( const GlsUInt32 row, const GlsUInt32 col ) const;

    /** Multiply this matrix by m where this matrix is on the left side and
      *  and m is on the right side of the multiplication,
      *  ( *this = (*this) * m )
      * \param m matrix to multiply by
      * \pre none
      * \post this matrix is multiplied by m ( *this * m )
      */
    void LeftMultiply( const GlsMatrixAffineD &m );

    /** Multiply this matrix by m where this matrix is on the right side and
      *  and m is on the left side of the multiplication,
      *  ( *this = m * (*this)  )
      * \param m matrix to multiply by
      * \pre none
      * \post this matrix is multiplied by m ( m * *this )
      */
    void RightMultiply( const GlsMatrixAffineD &m );

    /** Perform a rotation transformation around a major axis around the origin, 
      * and combine this transformation with the existing matrix data.
      * \param angle  rotation angle in degrees
      * \param rotationAxis   major axis of rotation
      * \pre GlsFloatIsValid( angle ),
      *      GlsMatrixAffineDRotationAxisIsValid( rotationAxis )
      * \post matrix is rotation transformed
      */
    void Rotate( const GlsFloat64 angle, const RotationAxis rotationAxis );

    /** Perform a translation using the given 3D vector and combine with this matrix
      * \param v 3D vector in question
      * \pre v.IsValid()
      * \post matrix is translated by v
      */
    void Translate( const GlsVector3D &v );

    /** populate the given GLMatrixAffineF with the values of the matrix
      * \param dst [out] gets values of the matrix
      * \pre none
      * \post dst contains values of the matrix
      */
    void PopulateGLMatrixAffineF( GLMatrixAffineF &dst ) const;

    /** Determine if the given c style matrix is the identity matrix
     * \param m c style matrix in question
     * \return GLS_TRUE if identity else GLS_FALSE
     * \pre GlsMatrixAffineDCStyleMatrixIsValid( m )
     * \post none
     */
    static GlsBool CStyleMatrixIsIdentity( const CStyleMatrix &m );

    /** Determine if the given GL matrix is identity
      * \param m matrix in question
      * \return GLS_TRUE if , is identity else GLS_FALSE
      * \pre GLMatrixAffineFIsValid( m )
      * \post none
      */
    static GlsBool GLMatrixAffineFIsIdentity( const GLMatrixAffineF &m );

    /** Copy a GLMatrixAffineF
      * \param dst [out] destination GLMatrixAffineF 
      * \param src source GLMatrixAffineF
      * \pre GLMatrixAffineFIsValid( src )
      * \post dst is a copy of src
      */
    static void CopyGLMatrixAffineF( GLMatrixAffineF &dst, const GLMatrixAffineF &src );

    /** Multiply the given 3D homogeneous vector by the given GL matrix
      * \param m GL matrix in question
      * \param v 3D homogeneous vector in question
      * \param dst [out] receives result ( m * v )
      * \pre GLMatrixAffineFIsValid( m ), v.IsValid()
      * \post dst = m * v
      */
    static void VectorMultGLMatrixAffineF( const GLMatrixAffineF &m, const GlsHomogeneousVector3D &v,
                                           GlsHomogeneousVector3D &dst );

    /** Multiply two GL matrices ( lhs, rhs ) and store in result
      * result = ( lhs * rhs )
      * \param lhs left hand side of multiplication
      * \param rhs right hand side of multiplication
      * \param result [out] gets resultant matrix form multiplication
      * \pre GLMatrixAffineFIsValid( lhs ), GLMatrixAffineFIsValid( rhs )
      * \post result = ( lhs * rhs )
      */
    static void MatrixMultGLMatrixAffineF( const GLMatrixAffineF &lhs, const GLMatrixAffineF &rhs,
                                           GLMatrixAffineF &result );

protected:
    /** identity c style matrix */
    static const GlsMatrixAffineD::CStyleMatrix IDENTITY_MATRIX_C_STYLE;
    /** identity matrix in data representation format */
    static const GlsFloat64 IDENTITY_MATRIX_DATA_REP[ DIMENSION * DIMENSION ];

    /** This is the actual matrix data stored in column-major ordering in
      * a one-dimensional array of the appropriate size to store all matrix
      * terms. The data is stored in this manner so that it can be passed
      * to OpenGL matrix operations, which expect matrices to be ordered
      * this way.
      */
    GlsFloat64 _data[ DIMENSION * DIMENSION ];

    /** A column index array. Each element in this array "points" 
      * to a column of the matrix within the above data. By using this index,
      * we can address matrix terms using two dimensions, column and row, 
      * without incurring a multiplication. Eg. matrix[0] points to a column
      * within data, which is the address of the first term in the column.
      * We can further address into the column and access a particular row
      * by adding another dimension, eg. matrix[0][1].  The indices must
      * be set up at construction time.
      */
    GlsFloat64 *_matrix[ DIMENSION ];

    /** This should be called from all constructors, as it initializes the
      * matrix column index so that matrix elements can be addressed in two
      * dimensions, but a multiplication is not incurred when doing so.
      * \pre none
      * \post _matrix elements are initialized
      */
    void Initialize( void );

    /** Set this matrix to the identity matrix. The identity matrix is 
      * I = [Aij], where Aii = 1 and Aij = 0 for i != j. Thus, for the identity 
      * matrix, the terms off the main diagonal are all zero, and the terms on 
      * the main diagonal are all one.
      * \pre none
      * \post matrix is identity matrix
      */
    void MakeIdentity( void );

    /** Multiply the two matrices ( lhs, rhs ) and store in result
      *  ( result = ( lhs * rhs )
      * \param lhs left hand side of multiplication
      * \param rhs right hand side of multiplication
      * \param result [out] gets resultant matrix for multiplication
      * \pre none
      * \post result = ( lhs * rhs )
      */
    void Multiply( const GlsMatrixAffineD &lhs, const GlsMatrixAffineD &rhs, GlsMatrixAffineD &result ) const;

private:
    // Disable implicit generated Members
    GlsMatrixAffineD& operator=( const GlsMatrixAffineD &rhs );
};

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given c style matrix is valid
  * \param mat c style matrix in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsMatrixAffineDCStyleMatrixIsValid( const GlsMatrixAffineD::CStyleMatrix &mat )
{
    GlsBool isValid = GLS_TRUE;

    // ensure all members are valid floats
    for( GlsUInt32 row = 0u; ( row < GlsMatrixAffineD::DIMENSION ) && isValid; ++row )
    {
        for( GlsUInt32 col = 0u; col < GlsMatrixAffineD::DIMENSION; ++col )
        {
            isValid = GlsFloatIsValid( mat[ row ][ col ] );
            if( !isValid )
            {
                break;
            }
        }
    }

    return( isValid );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given matrix rotation axis is valid ( GLS_DEBUG only )
  * \param rotationAxis rotation axis in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsMatrixAffineDRotationAxisIsValid( const GlsMatrixAffineD::RotationAxis rotationAxis )
{
    return( ( GlsMatrixAffineD::ROTATION_AXIS_X == rotationAxis ) ||
            ( GlsMatrixAffineD::ROTATION_AXIS_Y == rotationAxis ) ||
            ( GlsMatrixAffineD::ROTATION_AXIS_Z == rotationAxis ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL matrix is valid ( GLS_DEBUG only )
  * \param m GL matrix in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GLMatrixAffineFIsValid( const GlsMatrixAffineD::GLMatrixAffineF &m )
{
    GlsBool isValid = GLS_TRUE;

    for( GlsUInt32 index = 0u; ( index < ( GlsMatrixAffineD::DIMENSION * GlsMatrixAffineD::DIMENSION ) ) && isValid; 
         ++index )
    {
        isValid = GlsFloatIsValid( m[ index ] );
        GlsAssert( isValid );
    }

    return( isValid );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_MATRIXAFFINE_DOUBLE_H