ground/gcs/src/libs/eigen/doc/TutorialMapClass.dox

   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 }