X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-core.git;a=blobdiff_plain;f=dali%2Fpublic-api%2Fmath%2Fmatrix.h;h=91faed2a5e25b704a5d8745c8459d103f9aab9e4;hp=2385b629aadc3e78ecd9b72d8b04fb71da382ec5;hb=45e368e0ac84c31187a3812afca3d73268154559;hpb=719bb2f6939effe2a07155544667789553105518

diff --git a/dali/public-api/math/matrix.h b/dali/public-api/math/matrix.h
index 2385b62..91faed2 100644
--- a/dali/public-api/math/matrix.h
+++ b/dali/public-api/math/matrix.h
@@ -2,7 +2,7 @@
 #define __DALI_MATRIX_H__
 
 /*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2018 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,11 +38,25 @@ class Quaternion;
 /**
  * @brief The Matrix class represents transformations and projections.
  *
- * It is agnostic w.r.t. row/column major notation - it operates on a flat array.
- * Each axis is contiguous in memory, so the x axis corresponds to elements 0, 1, 2 and 3, the y axis dorresponds to elements 4, 5, 6, 7, etc.
+ * The matrix is stored as a flat array and is Column Major, i.e. the storage order is as follows (numbers represent
+ * indices of array):
+ *
+ * @code
+ *
+ * 0   4   8   12
+ * 1   5   9   13
+ * 2   6   10  14
+ * 3   7   11  15
+ *
+ * @endcode
+ *
+ * Each axis is contiguous in memory, so the x-axis corresponds to elements 0, 1, 2 and 3, the y-axis corresponds to
+ * elements 4, 5, 6, 7, the z-axis corresponds to elements 12, 13, 14 and 15, and the translation vector corresponds to
+ * elements 12, 13 and 14.
+ *
  * @SINCE_1_0.0
  */
-class DALI_IMPORT_API Matrix
+class DALI_CORE_API Matrix
 {
 public:
 
@@ -51,7 +65,7 @@ public:
   /**
    * @brief Constructor.
    *
-   * Zero initialises the matrix
+   * Zero initializes the matrix.
    * @SINCE_1_0.0
    */
   Matrix();
@@ -65,22 +79,17 @@ public:
   explicit Matrix( bool initialize );
 
   /**
-   * @brief Constructor
+   * @brief Constructor.
    *
-   * The matrix is initialised with the contents of 'array' which must contain 16 floats.
+   * The matrix is initialized with the contents of 'array' which must contain 16 floats.
    * The order of the values for a transform matrix is:
    *
    * @code
-   *
-   *   xAxis.x xAxis.y xAxis.z 0.0f
-   *   yAxis.x yAxis.y yAxis.z 0.0f
-   *   zAxis.x zAxis.y zAxis.z 0.0f
-   *   trans.x trans.y trans.z 1.0f
-   *
+   * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
    * @endcode
    *
    * @SINCE_1_0.0
-   * @param [in] array Pointer of 16 floats data
+   * @param[in] array Pointer of 16 floats data
    */
   explicit Matrix(const float* array);
 
@@ -96,7 +105,7 @@ public:
    * @brief Copy constructor.
    *
    * @SINCE_1_0.0
-   * @param [in] matrix A reference to the copied matrix
+   * @param[in] matrix A reference to the copied matrix
    */
   Matrix( const Matrix& matrix );
 
@@ -104,7 +113,7 @@ public:
    * @brief Assignment operator.
    *
    * @SINCE_1_0.0
-   * @param [in] matrix A reference to the copied matrix
+   * @param[in] matrix A reference to the copied matrix
    * @return A reference to this
    */
   Matrix& operator=( const Matrix& matrix );
@@ -129,12 +138,12 @@ public:
   void SetIdentityAndScale( const Vector3& scale );
 
   /**
-   * @brief Invert a transform Matrix.
+   * @brief Inverts a transform Matrix.
    *
    * Any Matrix representing only a rotation and/or translation
    * can be inverted using this function. It is faster and more accurate then using Invert().
    * @SINCE_1_0.0
-   * @param [out] result The inverse of this matrix
+   * @param[out] result The inverse of this matrix
    */
   void InvertTransform(Matrix& result) const;
 
@@ -144,7 +153,7 @@ public:
    * Using the Matrix invert function for the specific type
    * of matrix you are dealing with is faster, more accurate.
    * @SINCE_1_0.0
-   * @return true if successful
+   * @return True if successful
    */
   bool Invert();
 
@@ -158,7 +167,7 @@ public:
    * @brief Returns the xAxis from a Transform matrix.
    *
    * @SINCE_1_0.0
-   * @return the x axis
+   * @return The x axis
    */
   Vector3 GetXAxis() const;
 
@@ -166,7 +175,7 @@ public:
    * @brief Returns the yAxis from a Transform matrix.
    *
    * @SINCE_1_0.0
-   * @return the y axis
+   * @return The y axis
    */
   Vector3 GetYAxis() const;
 
@@ -174,7 +183,7 @@ public:
    * @brief Returns the zAxis from a Transform matrix.
    *
    * @SINCE_1_0.0
-   * @return the z axis
+   * @return The z axis
    */
   Vector3 GetZAxis() const;
 
@@ -210,7 +219,7 @@ public:
    *
    * This assumes the matrix is a transform matrix.
    * @SINCE_1_0.0
-   * @return the translation
+   * @return The translation
    * @note inlined for performance reasons (generates less code than a function call)
    */
   const Vector4& GetTranslation() const { return reinterpret_cast<const Vector4&>(mMatrix[12]); }
@@ -220,7 +229,7 @@ public:
    *
    * This assumes the matrix is a transform matrix.
    * @SINCE_1_0.0
-   * @return the translation
+   * @return The translation
    * @note inlined for performance reasons (generates less code than a function call)
    */
   const Vector3& GetTranslation3() const { return reinterpret_cast<const Vector3&>(mMatrix[12]); }
@@ -259,16 +268,11 @@ public:
    * The order of the values for a transform matrix is:
    *
    * @code
-   *
-   *   xAxis.x xAxis.y xAxis.z 0.0f
-   *   yAxis.x yAxis.y yAxis.z 0.0f
-   *   zAxis.x zAxis.y zAxis.z 0.0f
-   *   trans.x trans.y trans.z 1.0f
-   *
+   * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
    * @endcode
    *
    * @SINCE_1_0.0
-   * @return the matrix contents as an array of 16 floats.
+   * @return The matrix contents as an array of 16 floats
    * @note inlined for performance reasons (generates less code than a function call)
    */
   const float* AsFloat() const {return mMatrix;}
@@ -279,16 +283,11 @@ public:
    * The order of the values for a transform matrix is:
    *
    * @code
-   *
-   *   xAxis.x xAxis.y xAxis.z 0.0f
-   *   yAxis.x yAxis.y yAxis.z 0.0f
-   *   zAxis.x zAxis.y zAxis.z 0.0f
-   *   trans.x trans.y trans.z 1.0f
-   *
+   * [ xAxis.x, xAxis.y, xAxis.z, 0.0f, yAxis.x, yAxis.y, yAxis.z, 0.0f, zAxis.x, zAxis.y, zAxis.z, 0.0f, trans.x, trans.y, trans.z, 1.0f ]
    * @endcode
    *
    * @SINCE_1_0.0
-   * @return the matrix contents as an array of 16 floats.
+   * @return The matrix contents as an array of 16 floats
    * @note inlined for performance reasons (generates less code than a function call)
    */
   float* AsFloat() {return mMatrix;}
@@ -296,7 +295,10 @@ public:
   /**
    * @brief Function to multiply two matrices and store the result onto third.
    *
-   * Use this method in time critical path as it does not require temporaries
+   * Use this method in time critical path as it does not require temporaries.
+   *
+   * result = rhs * lhs
+   *
    * @SINCE_1_0.0
    * @param[out] result Result of the multiplication
    * @param[in] lhs Matrix, this can be same matrix as result
@@ -307,7 +309,7 @@ public:
   /**
    * @brief Function to multiply a matrix and quaternion and store the result onto third.
    *
-   * Use this method in time critical path as it does not require temporaries
+   * Use this method in time critical path as it does not require temporaries.
    * @SINCE_1_0.0
    * @param[out] result Result of the multiplication
    * @param[in] lhs Matrix, this can be same matrix as result
@@ -318,16 +320,18 @@ public:
   /**
    * @brief The multiplication operator.
    *
+   * Returned Vector = This Matrix * rhs
+   *
    * @SINCE_1_0.0
-   * @param[in] rhs The Matrix to multiply this by
-   * @return A matrix containing the result
+   * @param[in] rhs The Vector4 to multiply this by
+   * @return A Vector4 containing the result
    */
   Vector4 operator*(const Vector4& rhs) const;
 
   /**
    * @brief The equality operator.
    *
-   * Utilises appropriate machine epsilon values.
+   * Utilizes appropriate machine epsilon values.
    *
    * @SINCE_1_0.0
    * @param[in] rhs The Matrix to compare this to
@@ -338,7 +342,7 @@ public:
   /**
    * @brief The inequality operator.
    *
-   * Utilises appropriate machine epsilon values.
+   * Utilizes appropriate machine epsilon values.
    * @SINCE_1_0.0
    * @param[in] rhs The Matrix to compare this to
    * @return true if the matrices are not equal.
@@ -406,15 +410,15 @@ private:
 };
 
 /**
- * @brief Print a matrix.
+ * @brief Prints a matrix.
  *
- * It is printed in memory order, i.e. each printed row is contiguous in memory.
+ * It is printed in memory order.
  * @SINCE_1_0.0
- * @param[in] o The output stream operator.
- * @param[in] matrix The matrix to print.
- * @return The output stream operator.
+ * @param[in] o The output stream operator
+ * @param[in] matrix The matrix to print
+ * @return The output stream operator
  */
-DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
+DALI_CORE_API std::ostream& operator<< (std::ostream& o, const Matrix& matrix);
 
 // Allow Matrix to be treated as a POD type
 template <> struct TypeTraits< Matrix > : public BasicTypes< Matrix > { enum { IS_TRIVIAL_TYPE = true }; };