inc/FBaseFloatMatrix.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file        FBaseFloatMatrix.h
  19  * @brief       This is the header file for the %FloatMatrix class.
  20  *
  21  * This header file contains the declarations of the %FloatMatrix class.
  22  *
  23  */
  24 #ifndef _FBASE_FLOAT_MATRIX_H_
  25 #define _FBASE_FLOAT_MATRIX_H_
  26
  27 #include <FBase.h>
  28 #include <FBaseTypes.h>
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 /**
  34  * @class       FloatMatrix
  35  * @brief       This class encapsulates a two-dimensional matrix.
  36  *
  37  * @since 2.0
  38  *
  39  * The %FloatMatrix class provides a @c float precision, two-dimensional matrix class.
  40  *
  41  */
  42 class _OSP_EXPORT_ FloatMatrix
  43         : public Tizen::Base::Object
  44 {
  45 public:
  46         /**
  47          * Copying of objects using this copy constructor is allowed.
  48          *
  49          * @since 2.0
  50          *
  51          * @param[in]   rhs     An instance of %FloatMatrix
  52          */
  53         FloatMatrix(const FloatMatrix& rhs);
  54
  55         /**
  56          * Constructs a row by column null matrix in which all elements are zero.
  57          *
  58          * @since 2.0
  59          *
  60          * @param[in]   rowCount        The number of rows in the current instance
  61          * @param[in]   columnCount     The number of columns in the current instance
  62          */
  63         FloatMatrix(int rowCount, int columnCount);
  64
  65         /**
  66          * Constructs a row by column matrix initialized to the values in the specified array.
  67          *
  68          * @since 2.0
  69          *
  70          * @param[in]   rowCount        The number of rows in the current instance
  71          * @param[in]   columnCount     The number of columns in the current instance
  72          * @param[in]   pArray          A one-dimensional array @n The array must be at least row * column in length.
  73          * @param[in]   rowMajor        Set to @c true to copy the array in row-major order, @n
  74          *                                                      else @c copy in column-major order
  75          */
  76         FloatMatrix(int rowCount, int columnCount, const float* pArray, bool rowMajor = true);
  77
  78         /**
  79          * Constructs a row by column matrix initialized to the values in the specified array.
  80          *
  81          * @since 2.0
  82          *
  83          * @param[in]   rowCount        The number of rows in the current instance
  84          * @param[in]   columnCount     The number of columns in the current instance
  85          * @param[in]   pArray[]        A two-dimensional array @n The array must be at least row * column in length.
  86          */
  87         FloatMatrix(int rowCount, int columnCount, const float* pArray[]);
  88
  89         /**
  90          * This destructor overrides Tizen::Base::Object::~Object().
  91          *
  92          * @since 2.0
  93          */
  94         virtual ~FloatMatrix(void);
  95
  96         /**
  97          * Checks whether the current instance and the specified instance of %FloatMatrix are equal.
  98          *
  99          * @since 2.0
 100          *
 101          * @return      @c true if all matrix members of the current instance are equal to the corresponding matrix members in the specified instance, @n
 102          *                      else @c false
 103          * @param[in]   rhs     An instance of %FloatMatrix
 104          */
 105         bool operator ==(const FloatMatrix& rhs) const;
 106
 107         /**
 108          * Checks whether the current instance and the specified instance of %FloatMatrix are not equal.
 109          *
 110          * @since 2.0
 111          *
 112          * @return      @c true if all matrix members of the current instance are not equal to the corresponding matrix members in the specified instance, @n
 113          *                      else @c false
 114          * @param[in]   rhs     An instance of %FloatMatrix
 115          */
 116         bool operator !=(const FloatMatrix& rhs) const;
 117
 118         /**
 119          * Copying of objects using this copy assignment operator is allowed.
 120          *
 121          * @since 2.0
 122          *
 123          * @return              The reference to this instance
 124          * @param[in]   rhs     An instance of %FloatMatrix
 125          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 126          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 127          * @remarks             If either row or column count of the current instance is not same with that of the specified instance,
 128          *                              return the reference to this instance without assigning.
 129          */
 130         FloatMatrix& operator =(const FloatMatrix& rhs);
 131
 132         /**
 133          * Checks whether the current instance of %FloatMatrix equals the specified instance of %FloatMatrix.
 134          *
 135          * @since 2.0
 136          *
 137          * @return      @c true if the values of the current instance are equal to the value of the specified instance, @n
 138          *                      else @c false
 139          * @param[in]   obj     An instance of %FloatMatrix
 140          * @remarks             This method overrides Tizen::Base::Object::Equals(). This method uses the values of the Matrix components to compare the two instances.
 141          */
 142         virtual bool Equals(const Tizen::Base::Object& obj) const;
 143
 144         /**
 145          * Gets the hash value of the current instance of %FloatMatrix.
 146          *
 147          * @since 2.0
 148          *
 149          * @return      The hash value of the current instance
 150          * @remarks     Two equal instances must return the same hash value. For better performance,
 151          *                      the used hash function must generate a random distribution for all inputs.
 152          */
 153         virtual int GetHashCode(void) const;
 154
 155         /**
 156          * Adds the value of the specified instance to the current instance of %FloatMatrix.
 157          *
 158          * @since 2.0
 159          *
 160          * @return              An error code
 161          * @param[in]   matrix                  An instance of %FloatMatrix
 162          * @exception   E_SUCCESS               The method is successful.
 163          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 164          */
 165         result Add(const FloatMatrix& matrix);
 166
 167         /**
 168          * Adds the value to each matrix members of current instance of %FloatMatrix.
 169          *
 170          * @since 2.0
 171          *
 172          * @param[in]   value   A @c float value to add
 173          */
 174         void AddToEachElement(float value);
 175
 176         /**
 177          * Gets the number of column in the current instance of %FloatMatrix.
 178          *
 179          * @since 2.0
 180          *
 181          * @return      The number of column in the current instance
 182          */
 183         int GetColumnCount(void) const;
 184
 185         /**
 186          * Gets a new array that includes the values of the specified column in the current instance of %FloatMatrix.
 187          *
 188          * @since 2.0
 189          *
 190          * @return      A pointer to float array
 191          * @param[in]   columnIndex             The target column number in the current instance
 192          * @exception   E_INVALID_ARG   The @c columnIndex is larger than the column count of the current instance.
 193          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 194          */
 195         float* GetColumnN(int columnIndex) const;
 196
 197         /**
 198          * Gets the determinant of the current instance of %FloatMatrix.
 199          *
 200          * @since 2.0
 201          *
 202          * @return              The determinant value of the current instance
 203          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 204          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 205          * @remarks     If the current instance is not a square matrix, return zero.
 206          */
 207         float GetDeterminant(void) const;
 208
 209         /**
 210          * Gets the value at the specified row and column of the current instance of %FloatMatrix.
 211          *
 212          * @since 2.0
 213          *
 214          * @return      The value at the specified row and column of the current instance
 215          * @param[in]   rowIndex                The target row number in the current instance
 216          * @param[in]   columnIndex             The target column number in the current instance
 217          * @exception   E_INVALID_ARG   The @c columnIndex or @c rowIndex is larger than that of the current instance.
 218          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 219          */
 220         float GetElement(int rowIndex, int columnIndex) const;
 221
 222         /**
 223          * Gets the inverse matrix of the current instance of %FloatMatrix.
 224          *
 225          * @since 2.0
 226          *
 227          * @return              A pointer to the instance of %FloatMatrix containing the resulting value of the operation
 228          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 229          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 230          */
 231         FloatMatrix* GetInverseN(void) const;
 232
 233         /**
 234          * Gets the number of row in the current instance of %FloatMatrix.
 235          *
 236          * @since 2.0
 237          *
 238          * @return      The number of row in the current instance
 239          */
 240         int GetRowCount(void) const;
 241
 242         /**
 243          * Gets a new array that includes the values of the specified row in the current instance of %FloatMatrix.
 244          *
 245          * @since 2.0
 246          *
 247          * @return      A pointer to @c float array
 248          * @param[in]   rowIndex                The target row number in the current instance
 249          * @exception   E_INVALID_ARG   The @c rowIndex is larger than the row count of the current instance.
 250          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 251          */
 252         float* GetRowN(int rowIndex) const;
 253
 254         /**
 255          * Gets the trace of the current instance of %FloatMatrix.
 256          *
 257          * @since 2.0
 258          *
 259          * @return              An error code
 260          * @param[out]  value           A @c float value
 261          * @exception   E_SUCCESS       The method is successful.
 262          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 263          */
 264         result GetTrace(float& value) const;
 265
 266         /**
 267          * Gets the transpose matrix of the current instance of %FloatMatrix.
 268          *
 269          * @since 2.0
 270          *
 271          * @return              A pointer to the instance of %FloatMatrix containing the resulting value of the operation
 272          * @exception   E_INVALID_OPERATION             The current instance is not a square matrix.
 273          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 274          */
 275         FloatMatrix* GetTransposeN(void) const;
 276
 277         /**
 278          * Checks whether the current instance is an identity matrix.
 279          *
 280          * @since 2.0
 281          *
 282          * @return      @c true if the matrix is an identity matrix, @n
 283          *                      else @c false
 284          */
 285         bool IsIdentity(void) const;
 286
 287         /**
 288          * Checks whether the current matrix is invertible.
 289          *
 290          * @since 2.0
 291          *
 292          * @return      @c true if the matrix is invertible, @n
 293          *                      else @c false
 294          */
 295         bool IsInvertible(void) const;
 296
 297         /**
 298          * Multiplies the value of the specified instance with the current instance of %FloatMatrix.
 299          *
 300          * @since 2.0
 301          *
 302          * @return              An error code
 303          * @param[in]   matrix                  An instance of %FloatMatrix
 304          * @exception   E_SUCCESS               The method is successful.
 305          * @exception   E_INVALID_ARG   The column count of the current instance is not same with the row count of the specified instance.
 306          */
 307         result Multiply(const FloatMatrix& matrix);
 308
 309         /**
 310          * Multiplies the value to each matrix members of current instance of %FloatMatrix.
 311          *
 312          * @since 2.0
 313          *
 314          * @param[in]   value   A @c float value to multiply
 315          */
 316         void Multiply(float value);
 317
 318         /**
 319          * Negates the matrix members of current instance of %FloatMatrix.
 320          *
 321          * @since 2.0
 322          */
 323         void Negate(void);
 324
 325         /**
 326          * Sets the value of the current instance of %FloatMatrix to its identity.
 327          *
 328          * @since 2.0
 329          *
 330          * @return              An error code
 331          * @exception   E_SUCCESS                       The method is successful.
 332          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 333          */
 334         result SetAsIdentity(void);
 335
 336         /**
 337          * Sets the value of the current instance of %FloatMatrix to its inverse.
 338          *
 339          * @since 2.0
 340          *
 341          * @return              An error code
 342          * @exception   E_SUCCESS                       The method is successful.
 343          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 344          */
 345         result Invert(void);
 346
 347         /**
 348          * Sets the value of the current instance of %FloatMatrix to its transpose.
 349          *
 350          * @since 2.0
 351          *
 352          * @return              An error code
 353          * @exception   E_SUCCESS                       The method is successful.
 354          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 355          */
 356         result Transpose(void);
 357
 358         /**
 359          * Sets the values of the specified array to the specified column of the current instance of %FloatMatrix.
 360          *
 361          * @since 2.0
 362          *
 363          * @return              An error code
 364          * @param[in]   columnIndex             The target column number in the current instance
 365          * @param[in]   pArray                  An array which includes the values @n The array must be at least row in length.
 366          * @exception   E_SUCCESS               The method is successful.
 367          * @exception   E_INVALID_ARG   The @c pArray is @c null, or the @c columnIndex is larger than the column count of the current instance.
 368          */
 369         result SetColumn(int columnIndex, const float* pArray);
 370
 371         /**
 372          * Sets the values of the specified array to the specified row of the current instance of %FloatMatrix.
 373          *
 374          * @since 2.0
 375          *
 376          * @return              An error code
 377          * @param[in]   rowIndex        The target row number in the current instance
 378          * @param[in]   pArray          An array which includes the values @n The array must be at least column in length.
 379          * @exception   E_SUCCESS               The method is successful.
 380          * @exception   E_INVALID_ARG   The @c pArray is @c null, or the @c rowIndex is larger than the row count of the current instance.
 381          */
 382         result SetRow(int rowIndex, const float* pArray);
 383
 384         /**
 385          * Sets the value to the specified row and column of the current instance of %FloatMatrix.
 386          *
 387          * @since 2.0
 388          *
 389          * @return              An error code
 390          * @param[in]   rowIndex        The target row number in the current instance
 391          * @param[in]   columnIndex     The target column number in the current instance
 392          * @param[in]   value           A @c float value
 393          * @exception   E_SUCCESS       The method is successful.
 394          * @exception   E_INVALID_ARG   The pArray is @c null, or the @c rowIndex is larger than the row count of the current instance,
 395          *                              or the @c columnIndex is larger than the column count of the current instance.
 396          */
 397         result SetElement(int rowIndex, int columnIndex, float value);
 398
 399         /**
 400          * Sets the values to the current instance of %FloatMatrix in either the row-major or column-major order.
 401          *
 402          * @since 2.0
 403          *
 404          * @return              An error code
 405          * @param[in]   pArray          A one-dimensional array @n The array must be at least row * column in length.
 406          * @param[in]   rowMajor        Set to @c true to copy the array in row-major order, @n
 407          *                                                      else @c false to copy in column-major order
 408          * @exception   E_SUCCESS               The method is successful.
 409          * @exception   E_INVALID_ARG   The pArray is @c null.
 410          */
 411         result SetValue(const float* pArray, bool rowMajor = true);
 412
 413         /**
 414          * Sets the matrix members of current instance of %FloatMatrix to zero.
 415          *
 416          * @since 2.0
 417          */
 418         void SetAsNull(void);
 419
 420         /**
 421          * Subtracts the value of the specified instance from the current instance of %FloatMatrix.
 422          *
 423          * @since 2.0
 424          *
 425          * @return              An error code
 426          * @param[in]   matrix                  An instance of %FloatMatrix
 427          * @exception   E_SUCCESS               The method is successful.
 428          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 429          */
 430         result Subtract(const FloatMatrix& matrix);
 431
 432         /**
 433          * Subtracts the value from each matrix members of current instance of %FloatMatrix.
 434          *
 435          * @since 2.0
 436          *
 437          * @param[in]   value   A @c float value to subtract
 438          */
 439         void SubtractToEachElement(float value);
 440
 441 private:
 442         /*
 443          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 444          *
 445          * @since 2.0
 446          */
 447         FloatMatrix(void);
 448
 449         bool AllocateCapacity(int rowCount, int columnCount);
 450         void GetMinor(float** pSrc, float** pDest, int rowIndex, int columnIndex, int order) const;
 451         float CalculateDeterminant(float** pMatrix, int order) const;
 452
 453         friend class _FloatMatrixImpl;
 454         class _FloatMatrixImpl* __pImpl;
 455
 456         float** __pMatrix;
 457         int __row;
 458         int __column;
 459
 460 }; // FloatMatrix
 461
 462 }} // Tizen::Base
 463
 464 #endif //_FBASE_FLOAT_MATRIX_H_