mirror of
https://gitlab.com/libeigen/eigen.git
synced 2025-06-04 18:54:00 +08:00
93ee82b1fd
- Organize the documentation into "chapters". - Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page. - The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ). - Add a "General topics" entry for all pages that do not fit well in the previous "chapters". - The highlevel struture is managed by a new eigendoxy_layout.xml file. - remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.) - add the javascript search-engine. - add the "treeview" panel. - remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed). - add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel. - overload various javascript function generated by doxygen to: - remove the root of the treeview - remove links to section/subsection from the treeview - automatically expand the "Chapters" section - automatically expand the current section - adjust the height of the treeview to take into account the TOC - always use the default .css file, eigendoxy.css now only includes our modifications - use Doxyfile to specify our logo - remove cross references to unsupported modules (temporarily)
63 lines
3.3 KiB
Plaintext
63 lines
3.3 KiB
Plaintext
namespace Eigen {
|
|
|
|
/** \eigenManualPage TopicStlContainers Using STL Containers with Eigen
|
|
|
|
\eigenAutoToc
|
|
|
|
\section summary Executive summary
|
|
|
|
Using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", or classes having members of such types, requires taking the following two steps:
|
|
|
|
\li A 16-byte-aligned allocator must be used. Eigen does provide one ready for use: aligned_allocator.
|
|
\li If you want to use the std::vector container, you need to \#include <Eigen/StdVector>.
|
|
|
|
These issues arise only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". For other Eigen types, such as Vector3f or MatrixXd, no special care is needed when using STL containers.
|
|
|
|
\section allocator Using an aligned allocator
|
|
|
|
STL containers take an optional template parameter, the allocator type. When using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you need tell the container to use an allocator that will always allocate memory at 16-byte-aligned locations. Fortunately, Eigen does provide such an allocator: Eigen::aligned_allocator.
|
|
|
|
For example, instead of
|
|
\code
|
|
std::map<int, Eigen::Vector4f>
|
|
\endcode
|
|
you need to use
|
|
\code
|
|
std::map<int, Eigen::Vector4f, std::less<int>,
|
|
Eigen::aligned_allocator<std::pair<const int, Eigen::Vector4f> > >
|
|
\endcode
|
|
Note that the third parameter "std::less<int>" is just the default value, but we have to include it because we want to specify the fourth parameter, which is the allocator type.
|
|
|
|
\section vector The case of std::vector
|
|
|
|
The situation with std::vector was even worse (explanation below) so we had to specialize it for the Eigen::aligned_allocator type. In practice you \b must use the Eigen::aligned_allocator (not another aligned allocator), \b and \#include <Eigen/StdVector>.
|
|
|
|
Here is an example:
|
|
\code
|
|
#include<Eigen/StdVector>
|
|
/* ... */
|
|
std::vector<Eigen::Vector4f,Eigen::aligned_allocator<Eigen::Vector4f> >
|
|
\endcode
|
|
|
|
\subsection vector_spec An alternative - specializing std::vector for Eigen types
|
|
|
|
As an alternative to the recommended approach described above, you have the option to specialize std::vector for Eigen types requiring alignment.
|
|
The advantage is that you won't need to declare std::vector all over with Eigen::allocator. One drawback on the other hand side is that
|
|
the specialization needs to be defined before all code pieces in which e.g. std::vector<Vector2d> is used. Otherwise, without knowing the specialization
|
|
the compiler will compile that particular instance with the default std::allocator and you program is most likely to crash.
|
|
|
|
Here is an example:
|
|
\code
|
|
#include<Eigen/StdVector>
|
|
/* ... */
|
|
EIGEN_DEFINE_STL_VECTOR_SPECIALIZATION(Matrix2d)
|
|
std::vector<Eigen::Vector2d>
|
|
\endcode
|
|
|
|
<span class="note">\b Explanation: The resize() method of std::vector takes a value_type argument (defaulting to value_type()). So with std::vector<Eigen::Vector4f>, some Eigen::Vector4f objects will be passed by value, which discards any alignment modifiers, so a Eigen::Vector4f can be created at an unaligned location. In order to avoid that, the only solution we saw was to specialize std::vector to make it work on a slight modification of, here, Eigen::Vector4f, that is able to deal properly with this situation.
|
|
</span>
|
|
|
|
*/
|
|
|
|
}
|