Renamed allowAligned() => forceAligned() and added the constants ForceAligned

and AsRequested for the PacketAccess parameter of MapBase. Updated respective
documentation.

5 files changed, 44 insertions, 30 deletions

diff --git a/Eigen/src/Core/Block.h b/Eigen/src/Core/Block.h
index c2c9606a5..917175bfd 100644
--- a/Eigen/src/Core/Block.h
+++ b/Eigen/src/Core/Block.h
@@ -33,7 +33,10 @@
   * \param MatrixType the type of the object in which we are taking a block
   * \param BlockRows the number of rows of the block we are taking at compile time (optional)
   * \param BlockCols the number of columns of the block we are taking at compile time (optional)
-  * \param _PacketAccess 
+  * \param _PacketAccess allows to enforce aligned loads and stores if set to ForceAligned.
+  *                      The default is AsRequested. This parameter is internaly used by Eigen
+  *                      in expressions such as \code mat.block() += other; \endcode and most of
+  *                      the time this is the only way it is used.
   * \param _DirectAccessStatus \internal used for partial specialization
   *
   * This class represents an expression of either a fixed-size or dynamic-size block. It is the return
@@ -84,9 +87,9 @@ struct ei_traits<Block<MatrixType, BlockRows, BlockCols, _PacketAccess, _DirectA
     CoeffReadCost = MatrixType::CoeffReadCost,
     PacketAccess = _PacketAccess
   };
-  typedef typename ei_meta_if<int(PacketAccess)==Aligned,
+  typedef typename ei_meta_if<int(PacketAccess)==ForceAligned,
                  Block<MatrixType, BlockRows, BlockCols, _PacketAccess, _DirectAccessStatus>&,
-                 Block<MatrixType, BlockRows, BlockCols, Aligned, _DirectAccessStatus> >::ret AlignedDerivedType;
+                 Block<MatrixType, BlockRows, BlockCols, ForceAligned, _DirectAccessStatus> >::ret AlignedDerivedType;
 };
 
 template<typename MatrixType, int BlockRows, int BlockCols, int PacketAccess, int _DirectAccessStatus> class Block
@@ -223,12 +226,12 @@ class Block<MatrixType,BlockRows,BlockCols,PacketAccess,HasDirectAccess>
 
     EIGEN_INHERIT_ASSIGNMENT_OPERATORS(Block)
 
-    AlignedDerivedType allowAligned()
+    AlignedDerivedType forceAligned()
     {
-      if (PacketAccess==Aligned)
+      if (PacketAccess==ForceAligned)
         return *this;
       else
-        return Block<MatrixType,BlockRows,BlockCols,Aligned,HasDirectAccess>
+        return Block<MatrixType,BlockRows,BlockCols,ForceAligned,HasDirectAccess>
                     (m_matrix, Base::m_data, Base::m_rows.value(), Base::m_cols.value());
     }
 
diff --git a/Eigen/src/Core/Map.h b/Eigen/src/Core/Map.h
index a1953993f..85fbcc0f0 100644
--- a/Eigen/src/Core/Map.h
+++ b/Eigen/src/Core/Map.h
@@ -30,8 +30,11 @@
   *
   * \brief A matrix or vector expression mapping an existing array of data.
   *
-  * \param _PacketAccess controls whether vectorized aligned loads or stores are allowed (Aligned)
-  *                      or forced to unaligned (Unaligned). Defaults to Unaligned.
+  * \param MatrixType the equivalent matrix type of the mapped data
+  * \param _PacketAccess allows to enforce aligned loads and stores if set to ForceAligned.
+  *                      The default is AsRequested. This parameter is internaly used by Eigen
+  *                      in expressions such as \code Map<...>(...) += other; \endcode and most
+  *                      of the time this is the only way it is used.
   *
   * This class represents a matrix or vector expression mapping an existing array of data.
   * It can be used to let Eigen interface without any overhead with non-Eigen data structures,
@@ -48,9 +51,9 @@ struct ei_traits<Map<MatrixType, _PacketAccess> > : public ei_traits<MatrixType>
     PacketAccess = _PacketAccess,
     Flags = ei_traits<MatrixType>::Flags & ~AlignedBit
   };
-  typedef typename ei_meta_if<int(PacketAccess)==Aligned,
+  typedef typename ei_meta_if<int(PacketAccess)==ForceAligned,
                               Map<MatrixType, _PacketAccess>&,
-                              Map<MatrixType, Aligned> >::ret AlignedDerivedType;
+                              Map<MatrixType, ForceAligned> >::ret AlignedDerivedType;
 };
 
 template<typename MatrixType, int PacketAccess> class Map
@@ -63,12 +66,12 @@ template<typename MatrixType, int PacketAccess> class Map
 
     inline int stride() const { return this->innerSize(); }
 
-    AlignedDerivedType allowAligned()
+    AlignedDerivedType forceAligned()
     {
-      if (PacketAccess==Aligned)
+      if (PacketAccess==ForceAligned)
         return *this;
       else
-        return Map<MatrixType,Aligned>(Base::m_data, Base::m_rows.value(), Base::m_cols.value());
+        return Map<MatrixType,ForceAligned>(Base::m_data, Base::m_rows.value(), Base::m_cols.value());
     }
 
     inline Map(const Scalar* data) : Base(data) {}
diff --git a/Eigen/src/Core/MapBase.h b/Eigen/src/Core/MapBase.h
index 0b54ca7b8..4c1a0cf2f 100644
--- a/Eigen/src/Core/MapBase.h
+++ b/Eigen/src/Core/MapBase.h
@@ -26,12 +26,18 @@
 #ifndef EIGEN_MAPBASE_H
 #define EIGEN_MAPBASE_H
 
-/** \internal
-  *
-  * \class MapBase
+/** \class MapBase
   *
   * \brief Base class for Map and Block expression with direct access
   *
+  * Expression classes inheriting MapBase must define the constant \c PacketAccess,
+  * and type \c AlignedDerivedType in their respective ei_traits<> specialization structure.
+  * The value of \c PacketAccess can be either:
+  *  - \b ForceAligned which enforces both aligned loads and stores
+  *  - \b AsRequested which is the default behavior
+  * The type \c AlignedDerivedType should correspond to the equivalent expression type
+  * with \c PacketAccess being \c ForceAligned.
+  *
   * \sa class Map, class Block
   */
 template<typename Derived> class MapBase
@@ -57,7 +63,10 @@ template<typename Derived> class MapBase
     inline int cols() const { return m_cols.value(); }
 
     inline int stride() const { return derived().stride(); }
-    AlignedDerivedType allowAligned() { return derived().allowAligned(); }
+
+    /** \Returns an expression equivalent to \c *this but having the \c PacketAccess constant
+      * set to \c ForceAligned. Must be reimplemented by the derived class. */
+    AlignedDerivedType forceAligned() { return derived().forceAligned(); }
 
     inline const Scalar& coeff(int row, int col) const
     {
@@ -92,7 +101,7 @@ template<typename Derived> class MapBase
     template<int LoadMode>
     inline PacketScalar packet(int row, int col) const
     {
-      return ei_ploadt<Scalar, int(PacketAccess) == Aligned ? Aligned : LoadMode>
+      return ei_ploadt<Scalar, int(PacketAccess) == ForceAligned ? Aligned : LoadMode>
                (m_data + (IsRowMajor ? col + row * stride()
                                      : row + col * stride()));
     }
@@ -100,13 +109,13 @@ template<typename Derived> class MapBase
     template<int LoadMode>
     inline PacketScalar packet(int index) const
     {
-      return ei_ploadt<Scalar, int(PacketAccess) == Aligned ? Aligned : LoadMode>(m_data + index);
+      return ei_ploadt<Scalar, int(PacketAccess) == ForceAligned ? Aligned : LoadMode>(m_data + index);
     }
 
     template<int StoreMode>
     inline void writePacket(int row, int col, const PacketScalar& x)
     {
-      ei_pstoret<Scalar, PacketScalar, int(PacketAccess) == Aligned ? Aligned : StoreMode>
+      ei_pstoret<Scalar, PacketScalar, int(PacketAccess) == ForceAligned ? Aligned : StoreMode>
                (const_cast<Scalar*>(m_data) + (IsRowMajor ? col + row * stride()
                                                           : row + col * stride()), x);
     }
@@ -114,7 +123,7 @@ template<typename Derived> class MapBase
     template<int StoreMode>
     inline void writePacket(int index, const PacketScalar& x)
     {
-      ei_pstoret<Scalar, PacketScalar, int(PacketAccess) == Aligned ? Aligned : StoreMode>
+      ei_pstoret<Scalar, PacketScalar, int(PacketAccess) == ForceAligned ? Aligned : StoreMode>
         (const_cast<Scalar*>(m_data) + index, x);
     }
 
@@ -142,21 +151,19 @@ template<typename Derived> class MapBase
 
     EIGEN_INHERIT_ASSIGNMENT_OPERATORS(MapBase)
 
-//     EIGEN_INHERIT_ASSIGNMENT_OPERATOR(MapBase, =)
-
     template<typename OtherDerived>
     Derived& operator+=(const MatrixBase<OtherDerived>& other)
-    { return derived() = allowAligned() + other; }
+    { return derived() = forceAligned() + other; }
     
     template<typename OtherDerived>
     Derived& operator-=(const MatrixBase<OtherDerived>& other)
-    { return derived() = allowAligned() - other; }
+    { return derived() = forceAligned() - other; }
 
     Derived& operator*=(const Scalar& other)
-    { return derived() = allowAligned() * other; }
+    { return derived() = forceAligned() * other; }
     
     Derived& operator/=(const Scalar& other)
-    { return derived() = allowAligned() / other; }
+    { return derived() = forceAligned() / other; }
 
   protected:
     const Scalar* __restrict__ m_data;
diff --git a/Eigen/src/Core/util/Constants.h b/Eigen/src/Core/util/Constants.h
index ea3994544..2885a41fc 100644
--- a/Eigen/src/Core/util/Constants.h
+++ b/Eigen/src/Core/util/Constants.h
@@ -180,7 +180,8 @@ const unsigned int UnitUpper = UpperTriangularBit | UnitDiagBit;
 const unsigned int UnitLower = LowerTriangularBit | UnitDiagBit;
 const unsigned int Diagonal = Upper | Lower;
 
-enum { Aligned=0, Unaligned=1, Unknown=2 };
+enum { Aligned, Unaligned };
+enum { ForceAligned, AsRequested };
 enum { ConditionalJumpCost = 5 };
 enum CornerType { TopLeft, TopRight, BottomLeft, BottomRight };
 enum DirectionType { Vertical, Horizontal };
diff --git a/Eigen/src/Core/util/ForwardDeclarations.h b/Eigen/src/Core/util/ForwardDeclarations.h
index 7a1f95443..77c6f297a 100644
--- a/Eigen/src/Core/util/ForwardDeclarations.h
+++ b/Eigen/src/Core/util/ForwardDeclarations.h
@@ -43,7 +43,7 @@ template<typename ExpressionType, unsigned int Added, unsigned int Removed> clas
 template<typename ExpressionType> class NestByValue;
 template<typename ExpressionType> class SwapWrapper;
 template<typename MatrixType> class Minor;
-template<typename MatrixType, int BlockRows=Dynamic, int BlockCols=Dynamic, int PacketAccess=Unaligned,
+template<typename MatrixType, int BlockRows=Dynamic, int BlockCols=Dynamic, int PacketAccess=AsRequested,
          int _DirectAccessStatus = ei_traits<MatrixType>::Flags&DirectAccessBit> class Block;
 template<typename MatrixType> class Transpose;
 template<typename MatrixType> class Conjugate;
@@ -53,7 +53,7 @@ template<typename BinaryOp,  typename Lhs, typename Rhs>  class CwiseBinaryOp;
 template<typename Lhs, typename Rhs, int ProductMode> class Product;
 template<typename CoeffsVectorType> class DiagonalMatrix;
 template<typename MatrixType> class DiagonalCoeffs;
-template<typename MatrixType, int PacketAccess = Unaligned> class Map;
+template<typename MatrixType, int PacketAccess = AsRequested> class Map;
 template<typename MatrixType, unsigned int Mode> class Part;
 template<typename MatrixType, unsigned int Mode> class Extract;
 template<typename ExpressionType> class Cwise;