1 // This file is part of Eigen, a lightweight C++ template library 2 // for linear algebra. 3 // 4 // Copyright (C) 2007-2010 Benoit Jacob <jacob.benoit.1 (at) gmail.com> 5 // Copyright (C) 2008 Gael Guennebaud <gael.guennebaud (at) 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_MAP_H 12 #define EIGEN_MAP_H 13 14 namespace Eigen { 15 16 /** \class Map 17 * \ingroup Core_Module 18 * 19 * \brief A matrix or vector expression mapping an existing array of data. 20 * 21 * \tparam PlainObjectType the equivalent matrix type of the mapped data 22 * \tparam MapOptions specifies whether the pointer is \c #Aligned, or \c #Unaligned. 23 * The default is \c #Unaligned. 24 * \tparam StrideType optionally specifies strides. By default, Map assumes the memory layout 25 * of an ordinary, contiguous array. This can be overridden by specifying strides. 26 * The type passed here must be a specialization of the Stride template, see examples below. 27 * 28 * This class represents a matrix or vector expression mapping an existing array of data. 29 * It can be used to let Eigen interface without any overhead with non-Eigen data structures, 30 * such as plain C arrays or structures from other libraries. By default, it assumes that the 31 * data is laid out contiguously in memory. You can however override this by explicitly specifying 32 * inner and outer strides. 33 * 34 * Here's an example of simply mapping a contiguous array as a \ref TopicStorageOrders "column-major" matrix: 35 * \include Map_simple.cpp 36 * Output: \verbinclude Map_simple.out 37 * 38 * If you need to map non-contiguous arrays, you can do so by specifying strides: 39 * 40 * Here's an example of mapping an array as a vector, specifying an inner stride, that is, the pointer 41 * increment between two consecutive coefficients. Here, we're specifying the inner stride as a compile-time 42 * fixed value. 43 * \include Map_inner_stride.cpp 44 * Output: \verbinclude Map_inner_stride.out 45 * 46 * Here's an example of mapping an array while specifying an outer stride. Here, since we're mapping 47 * as a column-major matrix, 'outer stride' means the pointer increment between two consecutive columns. 48 * Here, we're specifying the outer stride as a runtime parameter. Note that here \c OuterStride<> is 49 * a short version of \c OuterStride<Dynamic> because the default template parameter of OuterStride 50 * is \c Dynamic 51 * \include Map_outer_stride.cpp 52 * Output: \verbinclude Map_outer_stride.out 53 * 54 * For more details and for an example of specifying both an inner and an outer stride, see class Stride. 55 * 56 * \b Tip: to change the array of data mapped by a Map object, you can use the C++ 57 * placement new syntax: 58 * 59 * Example: \include Map_placement_new.cpp 60 * Output: \verbinclude Map_placement_new.out 61 * 62 * This class is the return type of PlainObjectBase::Map() but can also be used directly. 63 * 64 * \sa PlainObjectBase::Map(), \ref TopicStorageOrders 65 */ 66 67 namespace internal { 68 template<typename PlainObjectType, int MapOptions, typename StrideType> 69 struct traits<Map<PlainObjectType, MapOptions, StrideType> > 70 : public traits<PlainObjectType> 71 { 72 typedef traits<PlainObjectType> TraitsBase; 73 typedef typename PlainObjectType::Index Index; 74 typedef typename PlainObjectType::Scalar Scalar; 75 enum { 76 InnerStrideAtCompileTime = StrideType::InnerStrideAtCompileTime == 0 77 ? int(PlainObjectType::InnerStrideAtCompileTime) 78 : int(StrideType::InnerStrideAtCompileTime), 79 OuterStrideAtCompileTime = StrideType::OuterStrideAtCompileTime == 0 80 ? int(PlainObjectType::OuterStrideAtCompileTime) 81 : int(StrideType::OuterStrideAtCompileTime), 82 HasNoInnerStride = InnerStrideAtCompileTime == 1, 83 HasNoOuterStride = StrideType::OuterStrideAtCompileTime == 0, 84 HasNoStride = HasNoInnerStride && HasNoOuterStride, 85 IsAligned = bool(EIGEN_ALIGN) && ((int(MapOptions)&Aligned)==Aligned), 86 IsDynamicSize = PlainObjectType::SizeAtCompileTime==Dynamic, 87 KeepsPacketAccess = bool(HasNoInnerStride) 88 && ( bool(IsDynamicSize) 89 || HasNoOuterStride 90 || ( OuterStrideAtCompileTime!=Dynamic 91 && ((static_cast<int>(sizeof(Scalar))*OuterStrideAtCompileTime)%16)==0 ) ), 92 Flags0 = TraitsBase::Flags & (~NestByRefBit), 93 Flags1 = IsAligned ? (int(Flags0) | AlignedBit) : (int(Flags0) & ~AlignedBit), 94 Flags2 = (bool(HasNoStride) || bool(PlainObjectType::IsVectorAtCompileTime)) 95 ? int(Flags1) : int(Flags1 & ~LinearAccessBit), 96 Flags3 = is_lvalue<PlainObjectType>::value ? int(Flags2) : (int(Flags2) & ~LvalueBit), 97 Flags = KeepsPacketAccess ? int(Flags3) : (int(Flags3) & ~PacketAccessBit) 98 }; 99 private: 100 enum { Options }; // Expressions don't have Options 101 }; 102 } 103 104 template<typename PlainObjectType, int MapOptions, typename StrideType> class Map 105 : public MapBase<Map<PlainObjectType, MapOptions, StrideType> > 106 { 107 public: 108 109 typedef MapBase<Map> Base; 110 EIGEN_DENSE_PUBLIC_INTERFACE(Map) 111 112 typedef typename Base::PointerType PointerType; 113 #if EIGEN2_SUPPORT_STAGE <= STAGE30_FULL_EIGEN3_API 114 typedef const Scalar* PointerArgType; 115 inline PointerType cast_to_pointer_type(PointerArgType ptr) { return const_cast<PointerType>(ptr); } 116 #else 117 typedef PointerType PointerArgType; 118 inline PointerType cast_to_pointer_type(PointerArgType ptr) { return ptr; } 119 #endif 120 121 inline Index innerStride() const 122 { 123 return StrideType::InnerStrideAtCompileTime != 0 ? m_stride.inner() : 1; 124 } 125 126 inline Index outerStride() const 127 { 128 return StrideType::OuterStrideAtCompileTime != 0 ? m_stride.outer() 129 : IsVectorAtCompileTime ? this->size() 130 : int(Flags)&RowMajorBit ? this->cols() 131 : this->rows(); 132 } 133 134 /** Constructor in the fixed-size case. 135 * 136 * \param dataPtr pointer to the array to map 137 * \param a_stride optional Stride object, passing the strides. 138 */ 139 inline Map(PointerArgType dataPtr, const StrideType& a_stride = StrideType()) 140 : Base(cast_to_pointer_type(dataPtr)), m_stride(a_stride) 141 { 142 PlainObjectType::Base::_check_template_params(); 143 } 144 145 /** Constructor in the dynamic-size vector case. 146 * 147 * \param dataPtr pointer to the array to map 148 * \param a_size the size of the vector expression 149 * \param a_stride optional Stride object, passing the strides. 150 */ 151 inline Map(PointerArgType dataPtr, Index a_size, const StrideType& a_stride = StrideType()) 152 : Base(cast_to_pointer_type(dataPtr), a_size), m_stride(a_stride) 153 { 154 PlainObjectType::Base::_check_template_params(); 155 } 156 157 /** Constructor in the dynamic-size matrix case. 158 * 159 * \param dataPtr pointer to the array to map 160 * \param nbRows the number of rows of the matrix expression 161 * \param nbCols the number of columns of the matrix expression 162 * \param a_stride optional Stride object, passing the strides. 163 */ 164 inline Map(PointerArgType dataPtr, Index nbRows, Index nbCols, const StrideType& a_stride = StrideType()) 165 : Base(cast_to_pointer_type(dataPtr), nbRows, nbCols), m_stride(a_stride) 166 { 167 PlainObjectType::Base::_check_template_params(); 168 } 169 170 EIGEN_INHERIT_ASSIGNMENT_OPERATORS(Map) 171 172 protected: 173 StrideType m_stride; 174 }; 175 176 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols> 177 inline Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> 178 ::Array(const Scalar *data) 179 { 180 this->_set_noalias(Eigen::Map<const Array>(data)); 181 } 182 183 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols> 184 inline Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> 185 ::Matrix(const Scalar *data) 186 { 187 this->_set_noalias(Eigen::Map<const Matrix>(data)); 188 } 189 190 } // end namespace Eigen 191 192 #endif // EIGEN_MAP_H 193
