1 namespace Eigen { 2 3 /** \page TutorialMapClass Tutorial page 10 - Interfacing with C/C++ arrays and external libraries: the %Map class 4 5 \ingroup Tutorial 6 7 \li \b Previous: \ref TutorialSparse 8 \li \b Next: \ref TODO 9 10 This tutorial page explains how to work with "raw" C++ arrays. This can be useful in a variety of contexts, particularly when "importing" vectors and matrices from other libraries into Eigen. 11 12 \b Table \b of \b contents 13 - \ref TutorialMapIntroduction 14 - \ref TutorialMapTypes 15 - \ref TutorialMapUsing 16 - \ref TutorialMapPlacementNew 17 18 \section TutorialMapIntroduction Introduction 19 20 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. 21 22 \section TutorialMapTypes Map types and declaring Map variables 23 24 A Map object has a type defined by its Eigen equivalent: 25 \code 26 Map<Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime> > 27 \endcode 28 Note that, in this default case, a Map requires just a single template parameter. 29 30 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: 31 \code 32 Map<MatrixXf> mf(pf,rows,columns); 33 \endcode 34 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 35 \code 36 Map<const Vector4i> mi(pi); 37 \endcode 38 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. 39 40 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). 41 42 Map is flexible enough to accomodate a variety of different data representations. There are two other (optional) template parameters: 43 \code 44 Map<typename MatrixType, 45 int MapOptions, 46 typename StrideType> 47 \endcode 48 \li \c MapOptions specifies whether the pointer is \c #Aligned, or \c #Unaligned. The default is \c #Unaligned. 49 \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: 50 <table class="example"> 51 <tr><th>Example:</th><th>Output:</th></tr> 52 <tr> 53 <td>\include Tutorial_Map_rowmajor.cpp </td> 54 <td>\verbinclude Tutorial_Map_rowmajor.out </td> 55 </table> 56 However, Stride is even more flexible than this; for details, see the documentation for the Map and Stride classes. 57 58 \section TutorialMapUsing Using Map variables 59 60 You can use a Map object just like any other Eigen type: 61 <table class="example"> 62 <tr><th>Example:</th><th>Output:</th></tr> 63 <tr> 64 <td>\include Tutorial_Map_using.cpp </td> 65 <td>\verbinclude Tutorial_Map_using.out </td> 66 </table> 67 68 However, when writing functions taking Eigen types, it is important to realize that a Map type is \em not identical to its Dense equivalent. See \ref TopicFunctionTakingEigenTypesMultiarguments for details. 69 70 \section TutorialMapPlacementNew Changing the mapped array 71 72 It is possible to change the array of a Map object after declaration, using the C++ "placement new" syntax: 73 <table class="example"> 74 <tr><th>Example:</th><th>Output:</th></tr> 75 <tr> 76 <td>\include Map_placement_new.cpp </td> 77 <td>\verbinclude Map_placement_new.out </td> 78 </table> 79 Despite appearances, this does not invoke the memory allocator, because the syntax specifies the location for storing the result. 80 81 This syntax makes it possible to declare a Map object without first knowing the mapped array's location in memory: 82 \code 83 Map<Matrix3f> A(NULL); // don't try to use this matrix yet! 84 VectorXf b(n_matrices); 85 for (int i = 0; i < n_matrices; i++) 86 { 87 new (&A) Map<Matrix3f>(get_matrix_pointer(i)); 88 b(i) = A.trace(); 89 } 90 \endcode 91 92 \li \b Next: \ref TODO 93 94 */ 95 96 } 97
