[136] | 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 | }
|
---|