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