mbed.org local branch of microbit-dal. The real version lives in git at https://github.com/lancaster-university/microbit-dal

Dependencies:   BLE_API nRF51822 mbed-dev-bin

Dependents:   microbit Microbit IoTChallenge1 microbit ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers Matrix4.h Source File

Matrix4.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 #ifndef MICROBIT_MATRIX4_H
00027 #define MICROBIT_MATRIX4_H
00028 
00029 #include "MicroBitConfig.h"
00030 
00031 /**
00032 * Class definition for a simple matrix, that is optimised for nx4 or 4xn matrices.
00033 *
00034 * This class is heavily optimised for these commonly used matrices as used in 3D geometry.
00035 * Whilst this class does support basic operations on matrices of any dimension, it is not intended as a
00036 * general purpose matrix class as inversion operations are only provided for 4x4 matrices.
00037 * For programmers needing more flexible Matrix support, the Matrix and MatrixMath classes from
00038 * Ernsesto Palacios provide a good basis:
00039 *
00040 * https://developer.mbed.org/cookbook/MatrixClass
00041 * https://developer.mbed.org/users/Yo_Robot/code/MatrixMath/
00042 */
00043 class Matrix4
00044 {
00045     float   *data;         // Linear buffer representing the matrix.
00046     int     rows;           // The number of rows in the matrix.
00047     int     cols;           // The number of columns in the matrix.
00048 
00049 public:
00050 
00051     /**
00052       * Constructor.
00053       * Create a matrix of the given size.
00054       *
00055       * @param rows the number of rows in the matrix to be created.
00056       *
00057       * @param cols the number of columns in the matrix to be created.
00058       *
00059       * @code
00060       * Matrix4(10, 4);        // Creates a Matrix with 10 rows and 4 columns.
00061       * @endcode
00062       */
00063     Matrix4(int rows, int cols);
00064 
00065     /**
00066       * Constructor.
00067       * Create a matrix that is an identical copy of the given matrix.
00068       *
00069       * @param matrix The matrix to copy.
00070       *
00071       * @code
00072       * Matrix newMatrix(matrix);        .
00073       * @endcode
00074       */
00075     Matrix4(const Matrix4 &matrix);
00076 
00077     /**
00078       * Determines the number of columns in this matrix.
00079       *
00080       * @return The number of columns in the matrix.
00081       *
00082       * @code
00083       * int c = matrix.width();
00084       * @endcode
00085       */
00086     int width();
00087 
00088     /**
00089       * Determines the number of rows in this matrix.
00090       *
00091       * @return The number of rows in the matrix.
00092       *
00093       * @code
00094       * int r = matrix.height();
00095       * @endcode
00096       */
00097     int height();
00098 
00099     /**
00100       * Reads the matrix element at the given position.
00101       *
00102       * @param row The row of the element to read.
00103       *
00104       * @param col The column of the element to read.
00105       *
00106       * @return The value of the matrix element at the given position. 0 is returned if the given index is out of range.
00107       *
00108       * @code
00109       * float v = matrix.get(1,2);
00110       * @endcode
00111       */
00112     float get(int row, int col);
00113 
00114     /**
00115       * Writes the matrix element at the given position.
00116       *
00117       * @param row The row of the element to write.
00118       *
00119       * @param col The column of the element to write.
00120       *
00121       * @param v The new value of the element.
00122       *
00123       * @code
00124       * matrix.set(1,2,42.0);
00125       * @endcode
00126       */
00127     void set(int row, int col, float v);
00128 
00129     /**
00130       * Transposes this matrix.
00131       *
00132       * @return the resultant matrix.
00133       *
00134       * @code
00135       * matrix.transpose();
00136       * @endcode
00137       */
00138     Matrix4 transpose();
00139 
00140     /**
00141       * Multiplies this matrix with the given matrix (if possible).
00142       *
00143       * @param matrix the matrix to multiply this matrix's values against.
00144       *
00145       * @param transpose Transpose the matrices before multiplication. Defaults to false.
00146       *
00147       * @return the resultant matrix. An empty matrix is returned if the operation canot be completed.
00148       *
00149       * @code
00150       * Matrix result = matrixA.multiply(matrixB);
00151       * @endcode
00152       */
00153     Matrix4 multiply(Matrix4 &matrix, bool transpose = false);
00154 
00155     /**
00156       * Multiplies the transpose of this matrix with the given matrix (if possible).
00157       *
00158       * @param matrix the matrix to multiply this matrix's values against.
00159       *
00160       * @return the resultant matrix. An empty matrix is returned if the operation canot be completed.
00161       *
00162       * @code
00163       * Matrix result = matrixA.multiplyT(matrixB);
00164       * @endcode
00165       */
00166     Matrix4 multiplyT(Matrix4 &matrix);
00167 
00168     /**
00169       * Performs an optimised inversion of a 4x4 matrix.
00170       * Only 4x4 matrices are supported by this operation.
00171       *
00172       * @return the resultant matrix. An empty matrix is returned if the operation canot be completed.
00173       *
00174       * @code
00175       * Matrix result = matrixA.invert();
00176       * @endcode
00177       */
00178     Matrix4 invert();
00179 
00180     /**
00181       * Destructor.
00182       *
00183       * Frees any memory consumed by this Matrix4 instance.
00184       */
00185     ~Matrix4();
00186 };
00187 
00188 /**
00189   * Multiplies the transpose of this matrix with the given matrix (if possible).
00190   *
00191   * @return the resultant matrix. An empty matrix is returned if the operation canot be completed.
00192   *
00193   * @code
00194   * Matrix result = matrixA.multiplyT(matrixB);
00195   * @endcode
00196   */
00197 inline Matrix4 Matrix4::multiplyT(Matrix4 &matrix)
00198 {
00199     return multiply(matrix, true);
00200 }
00201 
00202 #endif