1 namespace Eigen { 2 3 /** \eigenManualPage TutorialMapClass Interfacing with raw buffers: the Map class 4 5 This page explains how to work with "raw" C/C++ arrays. 6 This can be useful in a variety of contexts, particularly when "importing" vectors and matrices from other libraries into %Eigen. 7 8 \eigenAutoToc 9 10 \section TutorialMapIntroduction Introduction 11 12 Occasionally you may have a pre-defined array of numbers that you want to use within %Eigen as a vector or matrix. While one option is to make a copy of the data, most commonly you probably want to re-use this memory as an %Eigen type. Fortunately, this is very easy with the Map class. 13 14 \section TutorialMapTypes Map types and declaring Map variables 15 16 A Map object has a type defined by its %Eigen equivalent: 17 \code 18 Map<Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime> > 19 \endcode 20 Note that, in this default case, a Map requires just a single template parameter. 21 22 To construct a Map variable, you need two other pieces of information: a pointer to the region of memory defining the array of coefficients, and the desired shape of the matrix or vector. For example, to define a matrix of \c float with sizes determined at compile time, you might do the following: 23 \code 24 Map<MatrixXf> mf(pf,rows,columns); 25 \endcode 26 where \c pf is a \c float \c * pointing to the array of memory. A fixed-size read-only vector of integers might be declared as 27 \code 28 Map<const Vector4i> mi(pi); 29 \endcode 30 where \c pi is an \c int \c *. In this case the size does not have to be passed to the constructor, because it is already specified by the Matrix/Array type. 31 32 Note that Map does not have a default constructor; you \em must pass a pointer to intialize the object. However, you can work around this requirement (see \ref TutorialMapPlacementNew). 33 34 Map is flexible enough to accomodate a variety of different data representations. There are two other (optional) template parameters: 35 \code 36 Map<typename MatrixType, 37 int MapOptions, 38 typename StrideType> 39 \endcode 40 \li \c MapOptions specifies whether the pointer is \c #Aligned, or \c #Unaligned. The default is \c #Unaligned. 41 \li \c StrideType allows you to specify a custom layout for the memory array, using the Stride class. One example would be to specify that the data array is organized in row-major format: 42 <table class="example"> 43 <tr><th>Example:</th><th>Output:</th></tr> 44 <tr> 45 <td>\include Tutorial_Map_rowmajor.cpp </td> 46 <td>\verbinclude Tutorial_Map_rowmajor.out </td> 47 </table> 48 However, Stride is even more flexible than this; for details, see the documentation for the Map and Stride classes. 49 50 \section TutorialMapUsing Using Map variables 51 52 You can use a Map object just like any other %Eigen type: 53 <table class="example"> 54 <tr><th>Example:</th><th>Output:</th></tr> 55 <tr> 56 <td>\include Tutorial_Map_using.cpp </td> 57 <td>\verbinclude Tutorial_Map_using.out </td> 58 </table> 59 60 All %Eigen functions are written to accept Map objects just like other %Eigen types. However, when writing your own functions taking %Eigen types, this does \em not happen automatically: a Map type is not identical to its Dense equivalent. See \ref TopicFunctionTakingEigenTypes for details. 61 62 \section TutorialMapPlacementNew Changing the mapped array 63 64 It is possible to change the array of a Map object after declaration, using the C++ "placement new" syntax: 65 <table class="example"> 66 <tr><th>Example:</th><th>Output:</th></tr> 67 <tr> 68 <td>\include Map_placement_new.cpp </td> 69 <td>\verbinclude Map_placement_new.out </td> 70 </table> 71 Despite appearances, this does not invoke the memory allocator, because the syntax specifies the location for storing the result. 72 73 This syntax makes it possible to declare a Map object without first knowing the mapped array's location in memory: 74 \code 75 Map<Matrix3f> A(NULL); // don't try to use this matrix yet! 76 VectorXf b(n_matrices); 77 for (int i = 0; i < n_matrices; i++) 78 { 79 new (&A) Map<Matrix3f>(get_matrix_pointer(i)); 80 b(i) = A.trace(); 81 } 82 \endcode 83 84 */ 85 86 } 87
