matrix_4.h

Go to the documentation of this file.

/*
 * matrix_4.h
 *
 * Copyright (C) 2009,2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * 4x4 matrices, especially for 3D transformations.
 */

#ifndef WAVEPACKET_MATRIX_4_H__
#define WAVEPACKET_MATRIX_4_H__

// includes --------------------------------------------------------------------
#include "geometry_3d.h"


///\ingroup geometry
/*@{*/

////////////////////////////////////////////////////////////////////////////////
//
//      basic 4x4 matrix
//
////////////////////////////////////////////////////////////////////////////////

/// 4x4 matrix object.  Note that this matrix is especially optimized for 3D
///     transformations.
struct matrix4_t {

        // manipulators
        void clear(void) throw() { this->setZero(); }
        void setZero(void) throw();
        void setIdentity(void) throw() { this->setXYZScale(1.0); }

        void addTranslation(IN const point3d_t& t) throw();
        void operator += (IN const point3d_t& t) throw() {
                        this->addTranslation(t);
                }

        void setTranslation(IN const point3d_t& t) throw() {
                        this->setIdentity();
                        this->addTranslation(t);
                }
        void operator = (IN const point3d_t& t) throw() {
                        this->setTranslation(t);
                }

        const point3d_t getTranslation(void) const throw() {
                        return point3d_t(m[3], m[7], m[11]);
                }

        void setZRotation(IN float radians) throw();
        void setXRotation(IN float radians) throw();
        void setYRotation(IN float radians) throw();
        void setXYZScale(IN float r) throw();

        void transpose(void) throw();

        void dump(IN const char * txt) const throw();

        /// transforms 3D point p.  \b NOTE: assumes this 4x4 matrix is the
        ///     standard form for 3D transformations!
        point3d_t transform(IN const point3d_t& p) const throw();

        /// sets M = AB (note: order is important for matrix multiplication!)
        void setToProductOf(IN const matrix4_t& A,
                                IN const matrix4_t& B) throw();

        /// M = M + A
        /// \b CAREFUL: do you really want to do this?  Not legal for 3D xforms
        void addMatrix(IN const matrix4_t& A) throw();

        /// M = M - A
        /// \b CAREFUL: do you really want to do this?  Not legal for 3D xforms
        void subtractMatrix(IN const matrix4_t& B) throw();

        /// M = r * M
        /// \b CAREFUL: do you really want to do this?  Not legal for 3D xforms
        void scale(IN float r) throw();

        // raw data
        float           m[16];          // 4x4 raw data
};



inline matrix4_t operator * (IN const matrix4_t& A, IN const matrix4_t & B) throw()
        {
                matrix4_t M;
                M.setToProductOf(A, B);
                return M;
        }


inline point3d_t operator * (IN const matrix4_t& M, IN const point3d_t& p) throw()
        {
                return M.transform(p);
        }


inline matrix4_t operator + (IN const matrix4_t& M, IN const point3d_t t) throw()
        {
                matrix4_t M2 = M;
                M2.addTranslation(t);
                return M2;
        }

// NOTE: other operators aren't provided because they are invalid for 3D transforms



/// helper method to transform an array of points.  Caller must provide valid
///     input and output arrays, each of which must contain at least N points.
void transformPoints(IN const matrix4_t& T,
                        IN int N,
                        IN const point3d_t * inputPoints,
                        OUT point3d_t * outputPoints);


#endif  // WAVEPACKET_MATRIX_4_H__