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.
  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 to copy
  52          */
  53         FloatMatrix(const FloatMatrix& rhs);
  54
  55         /**
  56          * Constructs a row by column null matrix in which all the 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          The one-dimensional array @n
  73          *                                                      The array must be at least row * column in length.
  74          * @param[in]   rowMajor        Set to @c true to copy the array in row-major order, @n
  75          *                                                      else @c copy in column-major order
  76          */
  77         FloatMatrix(int rowCount, int columnCount, const float* pArray, bool rowMajor = true);
  78
  79         /**
  80          * Constructs a row by column matrix initialized to the values in the specified array.
  81          *
  82          * @since 2.0
  83          *
  84          * @param[in]   rowCount        The number of rows in the current instance
  85          * @param[in]   columnCount     The number of columns in the current instance
  86          * @param[in]   pArray[]        The two-dimensional array @n
  87          *                                                      The array must be at least row * column in length.
  88          */
  89         FloatMatrix(int rowCount, int columnCount, const float* pArray[]);
  90
  91         /**
  92          * This destructor overrides Tizen::Base::Object::~Object().
  93          *
  94          * @since 2.0
  95          */
  96         virtual ~FloatMatrix(void);
  97
  98         /**
  99          * Checks whether the current instance and the specified instance of %FloatMatrix are equal.
 100          *
 101          * @since 2.0
 102          *
 103          * @return      @c true if all the matrix members of the current instance are equal to the corresponding matrix members in the specified instance, @n
 104          *                      else @c false
 105          * @param[in]   rhs     An instance of %FloatMatrix
 106          */
 107         bool operator ==(const FloatMatrix& rhs) const;
 108
 109         /**
 110          * Checks whether the current instance and the specified instance of %FloatMatrix are not equal.
 111          *
 112          * @since 2.0
 113          *
 114          * @return              @c true if all the matrix members of the current instance are not equal to the corresponding matrix members in the specified instance, @n
 115          *                              else @c false
 116          * @param[in]   rhs     An instance of %FloatMatrix
 117          */
 118         bool operator !=(const FloatMatrix& rhs) const;
 119
 120         /**
 121          * Copying of objects using this copy assignment operator is allowed.
 122          *
 123          * @since 2.0
 124          *
 125          * @return              A reference to this instance
 126          * @param[in]   rhs     An instance of %FloatMatrix
 127          * @exception   E_INVALID_ARG   Either the row or the column count of the current instance is not same as that of the specified instance.
 128          * @remarks
 129          *                              - The specific error code can be accessed using the GetLastResult() method.
 130          *                              - If either the row or the column count of the current instance is not same as that of the specified instance,
 131          *                              this method returns the reference to this instance without assigning.
 132          */
 133         FloatMatrix& operator =(const FloatMatrix& rhs);
 134
 135         /**
 136          * Checks whether the current instance of %FloatMatrix equals the specified instance of %FloatMatrix.
 137          *
 138          * @since 2.0
 139          *
 140          * @return              @c true if the values of the current instance are equal to the value of the specified instance, @n
 141          *                              else @c false
 142          * @param[in]   obj     An instance of %FloatMatrix
 143          * @remarks
 144          *                              - This method overrides Tizen::Base::Object::Equals().
 145          *                              - This method uses the values of the Matrix components to compare the two instances.
 146          */
 147         virtual bool Equals(const Tizen::Base::Object& obj) const;
 148
 149         /**
 150          * Gets the hash value of the current instance of %FloatMatrix.
 151          *
 152          * @since 2.0
 153          *
 154          * @return      The hash value of the current instance
 155          * @remarks     Two equal instances must return the same hash value. @n
 156          *                      For better performance, the used hash function must generate a random distribution for all the inputs.
 157          */
 158         virtual int GetHashCode(void) const;
 159
 160         /**
 161          * Adds the value of the specified instance to the current instance of %FloatMatrix.
 162          *
 163          * @since 2.0
 164          *
 165          * @return              An error code
 166          * @param[in]   matrix                  An instance of %FloatMatrix
 167          * @exception   E_SUCCESS               The method is successful.
 168          * @exception   E_INVALID_ARG   Either the row or the column count of the current instance is not same as that of the specified instance.
 169          */
 170         result Add(const FloatMatrix& matrix);
 171
 172         /**
 173          * Adds the value to each matrix member of the current instance of %FloatMatrix.
 174          *
 175          * @since 2.0
 176          *
 177          * @param[in]   value   The @c float value to add
 178          */
 179         void AddToEachElement(float value);
 180
 181         /**
 182          * Gets the number of columns in the current instance of %FloatMatrix.
 183          *
 184          * @since 2.0
 185          *
 186          * @return      The number of columns in the current instance
 187          */
 188         int GetColumnCount(void) const;
 189
 190         /**
 191          * Gets a new array that includes the values of the specified column in the current instance of %FloatMatrix.
 192          *
 193          * @since 2.0
 194          *
 195          * @return              A pointer to the float array
 196          * @param[in]   columnIndex             The target column number in the current instance
 197          * @exception   E_INVALID_ARG   The specified @c columnIndex is larger than the column count of the current instance.
 198          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 199          */
 200         float* GetColumnN(int columnIndex) const;
 201
 202         /**
 203          * Gets the determinant of the current instance of %FloatMatrix.
 204          *
 205          * @since 2.0
 206          *
 207          * @return              The determinant value of the current instance
 208          * @exception   E_INVALID_OPERATION                     The current instance is not a square matrix.
 209          * @remarks
 210          *                              - The specific error code can be accessed using the GetLastResult() method.
 211          *                              - If the current instance is not a square matrix, it returns zero.
 212          */
 213         float GetDeterminant(void) const;
 214
 215         /**
 216          * Gets the value at the specified row and column of the current instance of %FloatMatrix.
 217          *
 218          * @since 2.0
 219          *
 220          * @return              The value at the specified row and column of the current instance
 221          * @param[in]   rowIndex                The target row number in the current instance
 222          * @param[in]   columnIndex             The target column number in the current instance
 223          * @exception   E_INVALID_ARG   The specified @c columnIndex or the specified @c rowIndex is larger than that of the current instance.
 224          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 225          */
 226         float GetElement(int rowIndex, int columnIndex) const;
 227
 228         /**
 229          * Gets the inverse matrix of the current instance of %FloatMatrix.
 230          *
 231          * @since 2.0
 232          *
 233          * @return              A pointer to the instance of %FloatMatrix that contains the resulting value of the operation
 234          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 235          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 236          */
 237         FloatMatrix* GetInverseN(void) const;
 238
 239         /**
 240          * Gets the number of rows in the current instance of %FloatMatrix.
 241          *
 242          * @since 2.0
 243          *
 244          * @return      The number of rows in the current instance
 245          */
 246         int GetRowCount(void) const;
 247
 248         /**
 249          * Gets a new array that includes the values of the specified row in the current instance of %FloatMatrix.
 250          *
 251          * @since 2.0
 252          *
 253          * @return              A pointer to the @c float array
 254          * @param[in]   rowIndex                The target row number in the current instance
 255          * @exception   E_INVALID_ARG   The specified @c rowIndex is larger than the row count of the current instance.
 256          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 257          */
 258         float* GetRowN(int rowIndex) const;
 259
 260         /**
 261          * Gets the trace of the current instance of %FloatMatrix.
 262          *
 263          * @since 2.0
 264          *
 265          * @return              An error code
 266          * @param[out]  value                           The @c float value
 267          * @exception   E_SUCCESS                       The method is successful.
 268          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 269          */
 270         result GetTrace(float& value) const;
 271
 272         /**
 273          * Gets the transpose matrix of the current instance of %FloatMatrix.
 274          *
 275          * @since 2.0
 276          *
 277          * @return              A pointer to the instance of %FloatMatrix that contains the resulting value of the operation
 278          * @exception   E_INVALID_OPERATION                     The current instance is not a square matrix.
 279          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 280          */
 281         FloatMatrix* GetTransposeN(void) const;
 282
 283         /**
 284          * Checks whether the current instance is an identity matrix.
 285          *
 286          * @since 2.0
 287          *
 288          * @return      @c true if the matrix is an identity matrix, @n
 289          *                      else @c false
 290          */
 291         bool IsIdentity(void) const;
 292
 293         /**
 294          * Checks whether the current matrix is invertible.
 295          *
 296          * @since 2.0
 297          *
 298          * @return      @c true if the matrix is invertible, @n
 299          *                      else @c false
 300          */
 301         bool IsInvertible(void) const;
 302
 303         /**
 304          * Multiplies the value of the specified instance with the current instance of %FloatMatrix.
 305          *
 306          * @since 2.0
 307          *
 308          * @return              An error code
 309          * @param[in]   matrix                  An instance of %FloatMatrix
 310          * @exception   E_SUCCESS               The method is successful.
 311          * @exception   E_INVALID_ARG   The column count of the current instance is not same as the row count of the specified instance.
 312          */
 313         result Multiply(const FloatMatrix& matrix);
 314
 315         /**
 316          * Multiplies the value to each matrix member of the current instance of %FloatMatrix.
 317          *
 318          * @since 2.0
 319          *
 320          * @param[in]   value   The @c float value to multiply
 321          */
 322         void Multiply(float value);
 323
 324         /**
 325          * Negates the matrix members of the current instance of %FloatMatrix.
 326          *
 327          * @since 2.0
 328          */
 329         void Negate(void);
 330
 331         /**
 332          * Sets the value of the current instance of %FloatMatrix to its identity.
 333          *
 334          * @since 2.0
 335          *
 336          * @return              An error code
 337          * @exception   E_SUCCESS                       The method is successful.
 338          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 339          */
 340         result SetAsIdentity(void);
 341
 342         /**
 343          * Sets the value of the current instance of %FloatMatrix to its inverse.
 344          *
 345          * @since 2.0
 346          *
 347          * @return              An error code
 348          * @exception   E_SUCCESS                       The method is successful.
 349          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 350          */
 351         result Invert(void);
 352
 353         /**
 354          * Sets the value of the current instance of %FloatMatrix to its transpose.
 355          *
 356          * @since 2.0
 357          *
 358          * @return              An error code
 359          * @exception   E_SUCCESS                       The method is successful.
 360          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 361          */
 362         result Transpose(void);
 363
 364         /**
 365          * Sets the values of the specified array to the specified column of the current instance of %FloatMatrix.
 366          *
 367          * @since 2.0
 368          *
 369          * @return              An error code
 370          * @param[in]   columnIndex             The target column number in the current instance
 371          * @param[in]   pArray                  The array which includes the values @n
 372          *                                                              The array must be at least row in length.
 373          * @exception   E_SUCCESS               The method is successful.
 374          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 375          *                                                              - The specified @c pArray is @c null.
 376          *                                                              - The specified @c columnIndex is larger than the column count of the current instance.
 377          */
 378         result SetColumn(int columnIndex, const float* pArray);
 379
 380         /**
 381          * Sets the values of the specified array to the specified row of the current instance of %FloatMatrix.
 382          *
 383          * @since 2.0
 384          *
 385          * @return              An error code
 386          * @param[in]   rowIndex                The target row number in the current instance
 387          * @param[in]   pArray                  The array which includes the values @n
 388          *                                                              The array must be at least column in length.
 389          * @exception   E_SUCCESS               The method is successful.
 390          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 391          *                                                              - The specified @c pArray is @c null.
 392          *                                                              - The specified @c rowIndex is larger than the row count of the current instance.
 393          */
 394         result SetRow(int rowIndex, const float* pArray);
 395
 396         /**
 397          * Sets the value to the specified row and column of the current instance of %FloatMatrix.
 398          *
 399          * @since 2.0
 400          *
 401          * @return              An error code
 402          * @param[in]   rowIndex                The target row number in the current instance
 403          * @param[in]   columnIndex             The target column number in the current instance
 404          * @param[in]   value                   The @c float value
 405          * @exception   E_SUCCESS               The method is successful.
 406          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 407          *                                                              - The specified @c pArray is @c null.
 408          *                                                              - The specified @c rowIndex is larger than the row count of the current instance.
 409          *                                                              - The specified @c columnIndex is larger than the column count of the current instance.
 410          */
 411         result SetElement(int rowIndex, int columnIndex, float value);
 412
 413         /**
 414          * Sets the values to the current instance of %FloatMatrix in either the row-major or column-major order.
 415          *
 416          * @since 2.0
 417          *
 418          * @return              An error code
 419          * @param[in]   pArray                  The one-dimensional array @n
 420          *                                                              The array must be at least row * column in length.
 421          * @param[in]   rowMajor                Set to @c true to copy the array in row-major order, @n
 422          *                                                              else @c false to copy in column-major order
 423          * @exception   E_SUCCESS               The method is successful.
 424          * @exception   E_INVALID_ARG   The specified @c pArray is @c null.
 425          */
 426         result SetValue(const float* pArray, bool rowMajor = true);
 427
 428         /**
 429          * Sets the matrix members of the current instance of %FloatMatrix to zero.
 430          *
 431          * @since 2.0
 432          */
 433         void SetAsNull(void);
 434
 435         /**
 436          * Subtracts the value of the specified instance from the current instance of %FloatMatrix.
 437          *
 438          * @since 2.0
 439          *
 440          * @return              An error code
 441          * @param[in]   matrix                  An instance of %FloatMatrix
 442          * @exception   E_SUCCESS               The method is successful.
 443          * @exception   E_INVALID_ARG   Either the row or the column count of the current instance is not same as that of the specified instance.
 444          */
 445         result Subtract(const FloatMatrix& matrix);
 446
 447         /**
 448          * Subtracts the value from each matrix member of the current instance of %FloatMatrix.
 449          *
 450          * @since 2.0
 451          *
 452          * @param[in]   value   The @c float value to subtract
 453          */
 454         void SubtractToEachElement(float value);
 455
 456 private:
 457         /*
 458          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 459          *
 460          * @since 2.0
 461          */
 462         FloatMatrix(void);
 463
 464         bool AllocateCapacity(int rowCount, int columnCount);
 465         void GetMinor(float** pSrc, float** pDest, int rowIndex, int columnIndex, int order) const;
 466         float CalculateDeterminant(float** pMatrix, int order) const;
 467
 468         friend class _FloatMatrixImpl;
 469         class _FloatMatrixImpl* __pImpl;
 470
 471         float** __pMatrix;
 472         int __row;
 473         int __column;
 474
 475 }; // FloatMatrix
 476
 477 }} // Tizen::Base
 478
 479 #endif //_FBASE_FLOAT_MATRIX_H_