* add CommaInitializer::finished to allow the use of (Matrix3() << v0, v1, v2).finished()

  as an argument of a function. Other possibilities for the name could be "end" or "matrix" ??
* various update in Quaternion, in particular I added a lot of FIXME about the API options,
  these have to be discussed and fixed.

3 files changed, 42 insertions, 10 deletions

diff --git a/Eigen/src/Core/CommaInitializer.h b/Eigen/src/Core/CommaInitializer.h
index 0a555e1b7..61a004780 100644
--- a/Eigen/src/Core/CommaInitializer.h
+++ b/Eigen/src/Core/CommaInitializer.h
@@ -93,6 +93,15 @@ struct MatrixBase<Derived>::CommaInitializer
          && "Too few coefficients passed to Matrix::operator<<");
   }
 
+  /** \returns the built matrix once all its coefficients have been set.
+    * Calling finished is 100% optional. Its purpose is to write expressions
+    * like this:
+    * \code
+    * quaternion.fromRotationMatrix((Matrix3f() << axis0, axis1, axis2).finished());
+    * \endcode
+    */
+  inline Derived& finished() { return m_matrix; }
+
   Derived& m_matrix;
   int m_row; // current row id
   int m_col; // current col id
diff --git a/Eigen/src/Core/MatrixBase.h b/Eigen/src/Core/MatrixBase.h
index 1ae2c4562..ea693b7a9 100644
--- a/Eigen/src/Core/MatrixBase.h
+++ b/Eigen/src/Core/MatrixBase.h
@@ -71,14 +71,14 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           * by the \a Derived type. If a value is not known at compile-time,
           * it is set to the \a Dynamic constant.
           * \sa MatrixBase::rows(), MatrixBase::cols(), RowsAtCompileTime, SizeAtCompileTime */
-        
+
 
       SizeAtCompileTime = (ei_size_at_compile_time<ei_traits<Derived>::RowsAtCompileTime,
                                                    ei_traits<Derived>::ColsAtCompileTime>::ret),
         /**< This is equal to the number of coefficients, i.e. the number of
           * rows times the number of columns, or to \a Dynamic if this is not
           * known at compile-time. \sa RowsAtCompileTime, ColsAtCompileTime */
-      
+
       MaxRowsAtCompileTime = ei_traits<Derived>::MaxRowsAtCompileTime,
         /**< This value is equal to the maximum possible number of rows that this expression
           * might have. If this expression might have an arbitrarily high number of rows,
@@ -89,7 +89,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           *
           * \sa RowsAtCompileTime, MaxColsAtCompileTime, MaxSizeAtCompileTime
           */
-        
+
       MaxColsAtCompileTime = ei_traits<Derived>::MaxColsAtCompileTime,
         /**< This value is equal to the maximum possible number of columns that this expression
           * might have. If this expression might have an arbitrarily high number of columns,
@@ -100,7 +100,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           *
           * \sa ColsAtCompileTime, MaxRowsAtCompileTime, MaxSizeAtCompileTime
           */
-        
+
       MaxSizeAtCompileTime = (ei_size_at_compile_time<ei_traits<Derived>::MaxRowsAtCompileTime,
                                                       ei_traits<Derived>::MaxColsAtCompileTime>::ret),
         /**< This value is equal to the maximum possible number of coefficients that this expression
@@ -119,7 +119,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           * columns is known at compile-time to be equal to 1. Indeed, in that case,
           * we are dealing with a column-vector (if there is only one column) or with
           * a row-vector (if there is only one row). */
-        
+
       Flags = ei_traits<Derived>::Flags,
         /**< This stores expression \ref flags flags which may or may not be inherited by new expressions
           * constructed from this one. See the \ref flags "list of flags".
diff --git a/Eigen/src/Geometry/Quaternion.h b/Eigen/src/Geometry/Quaternion.h
index 40b1ccdbd..1d0a3294f 100644
--- a/Eigen/src/Geometry/Quaternion.h
+++ b/Eigen/src/Geometry/Quaternion.h
@@ -168,7 +168,7 @@ public:
     inline Quaternion& operator*= (const Quaternion& q);
 
     Quaternion inverse(void) const;
-    Quaternion unitInverse(void) const;
+    Quaternion conjugate(void) const;
 
     Quaternion slerp(Scalar t, const Quaternion& other) const;
 
@@ -226,6 +226,11 @@ template<typename Scalar>
 inline typename Quaternion<Scalar>::Matrix3
 Quaternion<Scalar>::toRotationMatrix(void) const
 {
+  // FIXME another option would be to declare toRotationMatrix like that:
+  // OtherDerived& toRotationMatrix(MatrixBase<OtherDerived>& m)
+  // it would fill m and returns a ref to m.
+  // the advantages is that way we can accept 4x4 and 3x4 matrices filling the rest of the
+  // matrix with I... ??
   Matrix3 res;
 
   Scalar tx  = 2*this->x();
@@ -261,6 +266,7 @@ template<typename Scalar>
 template<typename Derived>
 Quaternion<Scalar>& Quaternion<Scalar>::fromRotationMatrix(const MatrixBase<Derived>& m)
 {
+  // FIXME maybe this function could accept 4x4 and 3x4 matrices as well ? (simply update the assert)
   ei_assert(Derived::RowsAtCompileTime==3 && Derived::ColsAtCompileTime==3);
   // This algorithm comes from  "Quaternion Calculus and Fast Animation",
   // Ken Shoemake, 1987 SIGGRAPH course notes
@@ -398,13 +404,19 @@ inline Quaternion<Scalar>& Quaternion<Scalar>::fromTwoVectors(const MatrixBase<D
   return *this;
 }
 
-/** \returns the inverse of \c *this */
+/** \returns the multiplicative inverse of \c *this
+  * Note that in most cases, i.e., if you simply want the opposite
+  * rotation, it is enough to use the conjugate.
+  *
+  * \sa Quaternion::conjugate()
+  */
 template <typename Scalar>
 inline Quaternion<Scalar> Quaternion<Scalar>::inverse() const
 {
+  // FIXME should this funtion be called multiplicativeInverse and conjugate() be called inverse() or opposite()  ??
   Scalar n2 = this->norm2();
   if (n2 > 0)
-    return (*this) / norm;
+    return conjugate() / n2;
   else
   {
     // return an invalid result to flag the error
@@ -412,9 +424,14 @@ inline Quaternion<Scalar> Quaternion<Scalar>::inverse() const
   }
 }
 
-/** Like Quaternion::inverse() but assumes the quaternion is normalized */
+/** \returns the conjugate of the \c *this which is equal to the multiplicative inverse
+  * if the quaternion is normalized.
+  * The conjugate of a quaternion represents the opposite rotation.
+  *
+  * \sa Quaternion::inverse()
+  */
 template <typename Scalar>
-inline Quaternion<Scalar> Quaternion<Scalar>::unitInverse() const
+inline Quaternion<Scalar> Quaternion<Scalar>::conjugate() const
 {
   return Quaternion(this->w(),-this->x(),-this->y(),-this->z());
 }
@@ -425,6 +442,12 @@ inline Quaternion<Scalar> Quaternion<Scalar>::unitInverse() const
 template <typename Scalar>
 Quaternion<Scalar> Quaternion<Scalar>::slerp(Scalar t, const Quaternion& other) const
 {
+  // FIXME options for this function would be:
+  // 1 - Quaternion& fromSlerp(Scalar t, const Quaternion& q0, const Quaternion& q1);
+  //     which set *this from the s-lerp and returns *this
+  // 2 - Quaternion slerp(Scalar t, const Quaternion& other) const
+  //     which returns the s-lerp between this and other
+  // ??
   if (*this == other)
     return *this;