1 // This file is part of Eigen, a lightweight C++ template library 2 // for linear algebra. 3 // 4 // Copyright (C) 2006-2010 Benoit Jacob <jacob.benoit.1@gmail.com> 5 // Copyright (C) 2008-2009 Gael Guennebaud <gael.guennebaud@inria.fr> 6 // 7 // This Source Code Form is subject to the terms of the Mozilla 8 // Public License v. 2.0. If a copy of the MPL was not distributed 9 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/. 10 11 #ifndef EIGEN_MATRIX_H 12 #define EIGEN_MATRIX_H 13 14 namespace Eigen { 15 16 namespace internal { 17 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols> 18 struct traits<Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > 19 { 20 private: 21 enum { size = internal::size_at_compile_time<_Rows,_Cols>::ret }; 22 typedef typename find_best_packet<_Scalar,size>::type PacketScalar; 23 enum { 24 row_major_bit = _Options&RowMajor ? RowMajorBit : 0, 25 is_dynamic_size_storage = _MaxRows==Dynamic || _MaxCols==Dynamic, 26 max_size = is_dynamic_size_storage ? Dynamic : _MaxRows*_MaxCols, 27 default_alignment = compute_default_alignment<_Scalar,max_size>::value, 28 actual_alignment = ((_Options&DontAlign)==0) ? default_alignment : 0, 29 required_alignment = unpacket_traits<PacketScalar>::alignment, 30 packet_access_bit = (packet_traits<_Scalar>::Vectorizable && (EIGEN_UNALIGNED_VECTORIZE || (actual_alignment>=required_alignment))) ? PacketAccessBit : 0 31 }; 32 33 public: 34 typedef _Scalar Scalar; 35 typedef Dense StorageKind; 36 typedef Eigen::Index StorageIndex; 37 typedef MatrixXpr XprKind; 38 enum { 39 RowsAtCompileTime = _Rows, 40 ColsAtCompileTime = _Cols, 41 MaxRowsAtCompileTime = _MaxRows, 42 MaxColsAtCompileTime = _MaxCols, 43 Flags = compute_matrix_flags<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols>::ret, 44 Options = _Options, 45 InnerStrideAtCompileTime = 1, 46 OuterStrideAtCompileTime = (Options&RowMajor) ? ColsAtCompileTime : RowsAtCompileTime, 47 48 // FIXME, the following flag in only used to define NeedsToAlign in PlainObjectBase 49 EvaluatorFlags = LinearAccessBit | DirectAccessBit | packet_access_bit | row_major_bit, 50 Alignment = actual_alignment 51 }; 52 }; 53 } 54 55 /** \class Matrix 56 * \ingroup Core_Module 57 * 58 * \brief The matrix class, also used for vectors and row-vectors 59 * 60 * The %Matrix class is the work-horse for all \em dense (\ref dense "note") matrices and vectors within Eigen. 61 * Vectors are matrices with one column, and row-vectors are matrices with one row. 62 * 63 * The %Matrix class encompasses \em both fixed-size and dynamic-size objects (\ref fixedsize "note"). 64 * 65 * The first three template parameters are required: 66 * \tparam _Scalar Numeric type, e.g. float, double, int or std::complex<float>. 67 * User defined scalar types are supported as well (see \ref user_defined_scalars "here"). 68 * \tparam _Rows Number of rows, or \b Dynamic 69 * \tparam _Cols Number of columns, or \b Dynamic 70 * 71 * The remaining template parameters are optional -- in most cases you don't have to worry about them. 72 * \tparam _Options A combination of either \b #RowMajor or \b #ColMajor, and of either 73 * \b #AutoAlign or \b #DontAlign. 74 * The former controls \ref TopicStorageOrders "storage order", and defaults to column-major. The latter controls alignment, which is required 75 * for vectorization. It defaults to aligning matrices except for fixed sizes that aren't a multiple of the packet size. 76 * \tparam _MaxRows Maximum number of rows. Defaults to \a _Rows (\ref maxrows "note"). 77 * \tparam _MaxCols Maximum number of columns. Defaults to \a _Cols (\ref maxrows "note"). 78 * 79 * Eigen provides a number of typedefs covering the usual cases. Here are some examples: 80 * 81 * \li \c Matrix2d is a 2x2 square matrix of doubles (\c Matrix<double, 2, 2>) 82 * \li \c Vector4f is a vector of 4 floats (\c Matrix<float, 4, 1>) 83 * \li \c RowVector3i is a row-vector of 3 ints (\c Matrix<int, 1, 3>) 84 * 85 * \li \c MatrixXf is a dynamic-size matrix of floats (\c Matrix<float, Dynamic, Dynamic>) 86 * \li \c VectorXf is a dynamic-size vector of floats (\c Matrix<float, Dynamic, 1>) 87 * 88 * \li \c Matrix2Xf is a partially fixed-size (dynamic-size) matrix of floats (\c Matrix<float, 2, Dynamic>) 89 * \li \c MatrixX3d is a partially dynamic-size (fixed-size) matrix of double (\c Matrix<double, Dynamic, 3>) 90 * 91 * See \link matrixtypedefs this page \endlink for a complete list of predefined \em %Matrix and \em Vector typedefs. 92 * 93 * You can access elements of vectors and matrices using normal subscripting: 94 * 95 * \code 96 * Eigen::VectorXd v(10); 97 * v[0] = 0.1; 98 * v[1] = 0.2; 99 * v(0) = 0.3; 100 * v(1) = 0.4; 101 * 102 * Eigen::MatrixXi m(10, 10); 103 * m(0, 1) = 1; 104 * m(0, 2) = 2; 105 * m(0, 3) = 3; 106 * \endcode 107 * 108 * This class can be extended with the help of the plugin mechanism described on the page 109 * \ref TopicCustomizing_Plugins by defining the preprocessor symbol \c EIGEN_MATRIX_PLUGIN. 110 * 111 * <i><b>Some notes:</b></i> 112 * 113 * <dl> 114 * <dt><b>\anchor dense Dense versus sparse:</b></dt> 115 * <dd>This %Matrix class handles dense, not sparse matrices and vectors. For sparse matrices and vectors, see the Sparse module. 116 * 117 * Dense matrices and vectors are plain usual arrays of coefficients. All the coefficients are stored, in an ordinary contiguous array. 118 * This is unlike Sparse matrices and vectors where the coefficients are stored as a list of nonzero coefficients.</dd> 119 * 120 * <dt><b>\anchor fixedsize Fixed-size versus dynamic-size:</b></dt> 121 * <dd>Fixed-size means that the numbers of rows and columns are known are compile-time. In this case, Eigen allocates the array 122 * of coefficients as a fixed-size array, as a class member. This makes sense for very small matrices, typically up to 4x4, sometimes up 123 * to 16x16. Larger matrices should be declared as dynamic-size even if one happens to know their size at compile-time. 124 * 125 * Dynamic-size means that the numbers of rows or columns are not necessarily known at compile-time. In this case they are runtime 126 * variables, and the array of coefficients is allocated dynamically on the heap. 127 * 128 * Note that \em dense matrices, be they Fixed-size or Dynamic-size, <em>do not</em> expand dynamically in the sense of a std::map. 129 * If you want this behavior, see the Sparse module.</dd> 130 * 131 * <dt><b>\anchor maxrows _MaxRows and _MaxCols:</b></dt> 132 * <dd>In most cases, one just leaves these parameters to the default values. 133 * These parameters mean the maximum size of rows and columns that the matrix may have. They are useful in cases 134 * when the exact numbers of rows and columns are not known are compile-time, but it is known at compile-time that they cannot 135 * exceed a certain value. This happens when taking dynamic-size blocks inside fixed-size matrices: in this case _MaxRows and _MaxCols 136 * are the dimensions of the original matrix, while _Rows and _Cols are Dynamic.</dd> 137 * </dl> 138 * 139 * <i><b>ABI and storage layout</b></i> 140 * 141 * The table below summarizes the ABI of some possible Matrix instances which is fixed thorough the lifetime of Eigen 3. 142 * <table class="manual"> 143 * <tr><th>Matrix type</th><th>Equivalent C structure</th></tr> 144 * <tr><td>\code Matrix<T,Dynamic,Dynamic> \endcode</td><td>\code 145 * struct { 146 * T *data; // with (size_t(data)%EIGEN_MAX_ALIGN_BYTES)==0 147 * Eigen::Index rows, cols; 148 * }; 149 * \endcode</td></tr> 150 * <tr class="alt"><td>\code 151 * Matrix<T,Dynamic,1> 152 * Matrix<T,1,Dynamic> \endcode</td><td>\code 153 * struct { 154 * T *data; // with (size_t(data)%EIGEN_MAX_ALIGN_BYTES)==0 155 * Eigen::Index size; 156 * }; 157 * \endcode</td></tr> 158 * <tr><td>\code Matrix<T,Rows,Cols> \endcode</td><td>\code 159 * struct { 160 * T data[Rows*Cols]; // with (size_t(data)%A(Rows*Cols*sizeof(T)))==0 161 * }; 162 * \endcode</td></tr> 163 * <tr class="alt"><td>\code Matrix<T,Dynamic,Dynamic,0,MaxRows,MaxCols> \endcode</td><td>\code 164 * struct { 165 * T data[MaxRows*MaxCols]; // with (size_t(data)%A(MaxRows*MaxCols*sizeof(T)))==0 166 * Eigen::Index rows, cols; 167 * }; 168 * \endcode</td></tr> 169 * </table> 170 * Note that in this table Rows, Cols, MaxRows and MaxCols are all positive integers. A(S) is defined to the largest possible power-of-two 171 * smaller to EIGEN_MAX_STATIC_ALIGN_BYTES. 172 * 173 * \see MatrixBase for the majority of the API methods for matrices, \ref TopicClassHierarchy, 174 * \ref TopicStorageOrders 175 */ 176 177 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols> 178 class Matrix 179 : public PlainObjectBase<Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > 180 { 181 public: 182 183 /** \brief Base class typedef. 184 * \sa PlainObjectBase 185 */ 186 typedef PlainObjectBase<Matrix> Base; 187 188 enum { Options = _Options }; 189 190 EIGEN_DENSE_PUBLIC_INTERFACE(Matrix) 191 192 typedef typename Base::PlainObject PlainObject; 193 194 using Base::base; 195 using Base::coeffRef; 196 197 /** 198 * \brief Assigns matrices to each other. 199 * 200 * \note This is a special case of the templated operator=. Its purpose is 201 * to prevent a default operator= from hiding the templated operator=. 202 * 203 * \callgraph 204 */ 205 EIGEN_DEVICE_FUNC 206 EIGEN_STRONG_INLINE Matrix& operator=(const Matrix& other) 207 { 208 return Base::_set(other); 209 } 210 211 /** \internal 212 * \brief Copies the value of the expression \a other into \c *this with automatic resizing. 213 * 214 * *this might be resized to match the dimensions of \a other. If *this was a null matrix (not already initialized), 215 * it will be initialized. 216 * 217 * Note that copying a row-vector into a vector (and conversely) is allowed. 218 * The resizing, if any, is then done in the appropriate way so that row-vectors 219 * remain row-vectors and vectors remain vectors. 220 */ 221 template<typename OtherDerived> 222 EIGEN_DEVICE_FUNC 223 EIGEN_STRONG_INLINE Matrix& operator=(const DenseBase<OtherDerived>& other) 224 { 225 return Base::_set(other); 226 } 227 228 /* Here, doxygen failed to copy the brief information when using \copydoc */ 229 230 /** 231 * \brief Copies the generic expression \a other into *this. 232 * \copydetails DenseBase::operator=(const EigenBase<OtherDerived> &other) 233 */ 234 template<typename OtherDerived> 235 EIGEN_DEVICE_FUNC 236 EIGEN_STRONG_INLINE Matrix& operator=(const EigenBase<OtherDerived> &other) 237 { 238 return Base::operator=(other); 239 } 240 241 template<typename OtherDerived> 242 EIGEN_DEVICE_FUNC 243 EIGEN_STRONG_INLINE Matrix& operator=(const ReturnByValue<OtherDerived>& func) 244 { 245 return Base::operator=(func); 246 } 247 248 /** \brief Default constructor. 249 * 250 * For fixed-size matrices, does nothing. 251 * 252 * For dynamic-size matrices, creates an empty matrix of size 0. Does not allocate any array. Such a matrix 253 * is called a null matrix. This constructor is the unique way to create null matrices: resizing 254 * a matrix to 0 is not supported. 255 * 256 * \sa resize(Index,Index) 257 */ 258 EIGEN_DEVICE_FUNC 259 EIGEN_STRONG_INLINE Matrix() : Base() 260 { 261 Base::_check_template_params(); 262 EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED 263 } 264 265 // FIXME is it still needed 266 EIGEN_DEVICE_FUNC 267 explicit Matrix(internal::constructor_without_unaligned_array_assert) 268 : Base(internal::constructor_without_unaligned_array_assert()) 269 { Base::_check_template_params(); EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED } 270 271 #if EIGEN_HAS_RVALUE_REFERENCES 272 EIGEN_DEVICE_FUNC 273 Matrix(Matrix&& other) EIGEN_NOEXCEPT_IF(std::is_nothrow_move_constructible<Scalar>::value) 274 : Base(std::move(other)) 275 { 276 Base::_check_template_params(); 277 } 278 EIGEN_DEVICE_FUNC 279 Matrix& operator=(Matrix&& other) EIGEN_NOEXCEPT_IF(std::is_nothrow_move_assignable<Scalar>::value) 280 { 281 other.swap(*this); 282 return *this; 283 } 284 #endif 285 286 #ifndef EIGEN_PARSED_BY_DOXYGEN 287 288 // This constructor is for both 1x1 matrices and dynamic vectors 289 template<typename T> 290 EIGEN_DEVICE_FUNC 291 EIGEN_STRONG_INLINE explicit Matrix(const T& x) 292 { 293 Base::_check_template_params(); 294 Base::template _init1<T>(x); 295 } 296 297 template<typename T0, typename T1> 298 EIGEN_DEVICE_FUNC 299 EIGEN_STRONG_INLINE Matrix(const T0& x, const T1& y) 300 { 301 Base::_check_template_params(); 302 Base::template _init2<T0,T1>(x, y); 303 } 304 #else 305 /** \brief Constructs a fixed-sized matrix initialized with coefficients starting at \a data */ 306 EIGEN_DEVICE_FUNC 307 explicit Matrix(const Scalar *data); 308 309 /** \brief Constructs a vector or row-vector with given dimension. \only_for_vectors 310 * 311 * This is useful for dynamic-size vectors. For fixed-size vectors, 312 * it is redundant to pass these parameters, so one should use the default constructor 313 * Matrix() instead. 314 * 315 * \warning This constructor is disabled for fixed-size \c 1x1 matrices. For instance, 316 * calling Matrix<double,1,1>(1) will call the initialization constructor: Matrix(const Scalar&). 317 * For fixed-size \c 1x1 matrices it is therefore recommended to use the default 318 * constructor Matrix() instead, especially when using one of the non standard 319 * \c EIGEN_INITIALIZE_MATRICES_BY_{ZERO,\c NAN} macros (see \ref TopicPreprocessorDirectives). 320 */ 321 EIGEN_STRONG_INLINE explicit Matrix(Index dim); 322 /** \brief Constructs an initialized 1x1 matrix with the given coefficient */ 323 Matrix(const Scalar& x); 324 /** \brief Constructs an uninitialized matrix with \a rows rows and \a cols columns. 325 * 326 * This is useful for dynamic-size matrices. For fixed-size matrices, 327 * it is redundant to pass these parameters, so one should use the default constructor 328 * Matrix() instead. 329 * 330 * \warning This constructor is disabled for fixed-size \c 1x2 and \c 2x1 vectors. For instance, 331 * calling Matrix2f(2,1) will call the initialization constructor: Matrix(const Scalar& x, const Scalar& y). 332 * For fixed-size \c 1x2 or \c 2x1 vectors it is therefore recommended to use the default 333 * constructor Matrix() instead, especially when using one of the non standard 334 * \c EIGEN_INITIALIZE_MATRICES_BY_{ZERO,\c NAN} macros (see \ref TopicPreprocessorDirectives). 335 */ 336 EIGEN_DEVICE_FUNC 337 Matrix(Index rows, Index cols); 338 339 /** \brief Constructs an initialized 2D vector with given coefficients */ 340 Matrix(const Scalar& x, const Scalar& y); 341 #endif 342 343 /** \brief Constructs an initialized 3D vector with given coefficients */ 344 EIGEN_DEVICE_FUNC 345 EIGEN_STRONG_INLINE Matrix(const Scalar& x, const Scalar& y, const Scalar& z) 346 { 347 Base::_check_template_params(); 348 EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Matrix, 3) 349 m_storage.data()[0] = x; 350 m_storage.data()[1] = y; 351 m_storage.data()[2] = z; 352 } 353 /** \brief Constructs an initialized 4D vector with given coefficients */ 354 EIGEN_DEVICE_FUNC 355 EIGEN_STRONG_INLINE Matrix(const Scalar& x, const Scalar& y, const Scalar& z, const Scalar& w) 356 { 357 Base::_check_template_params(); 358 EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Matrix, 4) 359 m_storage.data()[0] = x; 360 m_storage.data()[1] = y; 361 m_storage.data()[2] = z; 362 m_storage.data()[3] = w; 363 } 364 365 366 /** \brief Copy constructor */ 367 EIGEN_DEVICE_FUNC 368 EIGEN_STRONG_INLINE Matrix(const Matrix& other) : Base(other) 369 { } 370 371 /** \brief Copy constructor for generic expressions. 372 * \sa MatrixBase::operator=(const EigenBase<OtherDerived>&) 373 */ 374 template<typename OtherDerived> 375 EIGEN_DEVICE_FUNC 376 EIGEN_STRONG_INLINE Matrix(const EigenBase<OtherDerived> &other) 377 : Base(other.derived()) 378 { } 379 380 EIGEN_DEVICE_FUNC inline Index innerStride() const { return 1; } 381 EIGEN_DEVICE_FUNC inline Index outerStride() const { return this->innerSize(); } 382 383 /////////// Geometry module /////////// 384 385 template<typename OtherDerived> 386 EIGEN_DEVICE_FUNC 387 explicit Matrix(const RotationBase<OtherDerived,ColsAtCompileTime>& r); 388 template<typename OtherDerived> 389 EIGEN_DEVICE_FUNC 390 Matrix& operator=(const RotationBase<OtherDerived,ColsAtCompileTime>& r); 391 392 // allow to extend Matrix outside Eigen 393 #ifdef EIGEN_MATRIX_PLUGIN 394 #include EIGEN_MATRIX_PLUGIN 395 #endif 396 397 protected: 398 template <typename Derived, typename OtherDerived, bool IsVector> 399 friend struct internal::conservative_resize_like_impl; 400 401 using Base::m_storage; 402 }; 403 404 /** \defgroup matrixtypedefs Global matrix typedefs 405 * 406 * \ingroup Core_Module 407 * 408 * Eigen defines several typedef shortcuts for most common matrix and vector types. 409 * 410 * The general patterns are the following: 411 * 412 * \c MatrixSizeType where \c Size can be \c 2,\c 3,\c 4 for fixed size square matrices or \c X for dynamic size, 413 * and where \c Type can be \c i for integer, \c f for float, \c d for double, \c cf for complex float, \c cd 414 * for complex double. 415 * 416 * For example, \c Matrix3d is a fixed-size 3x3 matrix type of doubles, and \c MatrixXf is a dynamic-size matrix of floats. 417 * 418 * There are also \c VectorSizeType and \c RowVectorSizeType which are self-explanatory. For example, \c Vector4cf is 419 * a fixed-size vector of 4 complex floats. 420 * 421 * \sa class Matrix 422 */ 423 424 #define EIGEN_MAKE_TYPEDEFS(Type, TypeSuffix, Size, SizeSuffix) \ 425 /** \ingroup matrixtypedefs */ \ 426 typedef Matrix<Type, Size, Size> Matrix##SizeSuffix##TypeSuffix; \ 427 /** \ingroup matrixtypedefs */ \ 428 typedef Matrix<Type, Size, 1> Vector##SizeSuffix##TypeSuffix; \ 429 /** \ingroup matrixtypedefs */ \ 430 typedef Matrix<Type, 1, Size> RowVector##SizeSuffix##TypeSuffix; 431 432 #define EIGEN_MAKE_FIXED_TYPEDEFS(Type, TypeSuffix, Size) \ 433 /** \ingroup matrixtypedefs */ \ 434 typedef Matrix<Type, Size, Dynamic> Matrix##Size##X##TypeSuffix; \ 435 /** \ingroup matrixtypedefs */ \ 436 typedef Matrix<Type, Dynamic, Size> Matrix##X##Size##TypeSuffix; 437 438 #define EIGEN_MAKE_TYPEDEFS_ALL_SIZES(Type, TypeSuffix) \ 439 EIGEN_MAKE_TYPEDEFS(Type, TypeSuffix, 2, 2) \ 440 EIGEN_MAKE_TYPEDEFS(Type, TypeSuffix, 3, 3) \ 441 EIGEN_MAKE_TYPEDEFS(Type, TypeSuffix, 4, 4) \ 442 EIGEN_MAKE_TYPEDEFS(Type, TypeSuffix, Dynamic, X) \ 443 EIGEN_MAKE_FIXED_TYPEDEFS(Type, TypeSuffix, 2) \ 444 EIGEN_MAKE_FIXED_TYPEDEFS(Type, TypeSuffix, 3) \ 445 EIGEN_MAKE_FIXED_TYPEDEFS(Type, TypeSuffix, 4) 446 447 EIGEN_MAKE_TYPEDEFS_ALL_SIZES(int, i) 448 EIGEN_MAKE_TYPEDEFS_ALL_SIZES(float, f) 449 EIGEN_MAKE_TYPEDEFS_ALL_SIZES(double, d) 450 EIGEN_MAKE_TYPEDEFS_ALL_SIZES(std::complex<float>, cf) 451 EIGEN_MAKE_TYPEDEFS_ALL_SIZES(std::complex<double>, cd) 452 453 #undef EIGEN_MAKE_TYPEDEFS_ALL_SIZES 454 #undef EIGEN_MAKE_TYPEDEFS 455 #undef EIGEN_MAKE_FIXED_TYPEDEFS 456 457 } // end namespace Eigen 458 459 #endif // EIGEN_MATRIX_H 460