.
-These issues arise only with \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref StructHavingEigenMembers "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.
+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 FixedSizeVectorizable "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.
+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
diff --git a/doc/D03_WrongStackAlignment.dox b/doc/D03_WrongStackAlignment.dox
index 09711af9c..3e6fc03d6 100644
--- a/doc/D03_WrongStackAlignment.dox
+++ b/doc/D03_WrongStackAlignment.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page WrongStackAlignment Troubleshooting - Compiler making a wrong assumption on stack alignment
+/** \page TopicWrongStackAlignment Compiler making a wrong assumption on stack alignment
This is an issue that, so far, we met only with GCC on Windows: for instance, MinGW and TDM-GCC.
@@ -16,7 +16,7 @@ void foo()
GCC assumes that the stack is already 16-byte-aligned so that the object \a q will be created at a 16-byte-aligned location. For this reason, it doesn't take any special care to explicitly align the object \a q, as Eigen requires.
-The problem is that, in some particular cases, this assumption can be wrong on Windows, where the stack is only guaranteed to have 4-byte alignment. Indeed, even though GCC takes care of aligning the stack in the main function and does its best to keep it aligned, when a function is called from another thread or from a binary compiled with another compiler, the stack alignment can be corrupted. This results in the object 'q' being created at an unaligned location, making your program crash with the \ref UnalignedArrayAssert "assertion on unaligned arrays". So far we found the three following solutions.
+The problem is that, in some particular cases, this assumption can be wrong on Windows, where the stack is only guaranteed to have 4-byte alignment. Indeed, even though GCC takes care of aligning the stack in the main function and does its best to keep it aligned, when a function is called from another thread or from a binary compiled with another compiler, the stack alignment can be corrupted. This results in the object 'q' being created at an unaligned location, making your program crash with the \ref TopicUnalignedArrayAssert "assertion on unaligned arrays". So far we found the three following solutions.
\section sec_sol1 Local solution
@@ -38,7 +38,7 @@ A global solution is to edit your project so that when compiling with GCC on Win
\code
-mincoming-stack-boundary=2
\endcode
-Explanation: this tells GCC that the stack is only required to be aligned to 2^2=4 bytes, so that GCC now knows that it really must take extra care to honor the 16 byte alignment of \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types" when needed.
+Explanation: this tells GCC that the stack is only required to be aligned to 2^2=4 bytes, so that GCC now knows that it really must take extra care to honor the 16 byte alignment of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" when needed.
Another global solution is to pass this option to gcc:
\code
diff --git a/doc/D07_PassingByValue.dox b/doc/D07_PassingByValue.dox
index d15b375a6..b1e5e683b 100644
--- a/doc/D07_PassingByValue.dox
+++ b/doc/D07_PassingByValue.dox
@@ -1,10 +1,10 @@
namespace Eigen {
-/** \page PassingByValue Troubleshooting - Passing Eigen objects by value to functions
+/** \page TopicPassingByValue Passing Eigen objects by value to functions
Passing objects by value is almost always a very bad idea in C++, as this means useless copies, and one should pass them by reference instead.
-With Eigen, this is even more important: passing \ref FixedSizeVectorizable "fixed-size vectorizable Eigen objects" by value is not only inefficient, it can be illegal or make your program crash! And the reason is that these Eigen objects have alignment modifiers that aren't respected when they are passed by value.
+With Eigen, this is even more important: passing \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" by value is not only inefficient, it can be illegal or make your program crash! And the reason is that these Eigen objects have alignment modifiers that aren't respected when they are passed by value.
So for example, a function like this, where v is passed by value:
diff --git a/doc/D09_StructHavingEigenMembers.dox b/doc/D09_StructHavingEigenMembers.dox
index 07b6570dc..d6a24d951 100644
--- a/doc/D09_StructHavingEigenMembers.dox
+++ b/doc/D09_StructHavingEigenMembers.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page StructHavingEigenMembers Troubleshooting - Structures Having Eigen Members
+/** \page TopicStructHavingEigenMembers Structures Having Eigen Members
\b Table \b of \b contents
- \ref summary
@@ -13,7 +13,7 @@ namespace Eigen {
\section summary Executive Summary
-If you define a structure having members of \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you.
+If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you.
\section what What kind of code needs to be changed?
@@ -32,7 +32,7 @@ class Foo
Foo *foo = new Foo;
\endcode
-In other words: you have a class that has as a member a \ref FixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class.
+In other words: you have a class that has as a member a \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class.
\section how How should such code be modified?
@@ -102,7 +102,7 @@ public:
\section dynamicsize What about dynamic-size matrices and vectors?
-Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref FixedSizeVectorizable "fixed-size vectorizable matrices and vectors".
+Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable matrices and vectors".
\section bugineigen So is this a bug in Eigen?
diff --git a/doc/D11_UnalignedArrayAssert.dox b/doc/D11_UnalignedArrayAssert.dox
index 23ab3a94d..1a0e5140c 100644
--- a/doc/D11_UnalignedArrayAssert.dox
+++ b/doc/D11_UnalignedArrayAssert.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page UnalignedArrayAssert Troubleshooting - Explanation of the assertion on unaligned arrays
+/** \page TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays
Hello! You are seeing this webpage because your program terminated on an assertion failure like this one:
@@ -49,9 +49,9 @@ class Foo
Foo *foo = new Foo;
\endcode
-then you need to read this separate page: \ref StructHavingEigenMembers "Structures Having Eigen Members".
+then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members".
-Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
+Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
\section c2 Cause 2: STL Containers
@@ -63,9 +63,9 @@ struct my_class { ... Eigen::Matrix2f m; ... };
std::map my_map;
\endcode
-then you need to read this separate page: \ref StlContainers "Using STL Containers with Eigen".
+then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen".
-Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref StructHavingEigenMembers "structures having such Eigen objects as member".
+Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member".
\section c3 Cause 3: Passing Eigen objects by value
@@ -75,9 +75,9 @@ If some function in your code is getting an Eigen object passed by value, like t
void func(Eigen::Vector4d v);
\endcode
-then you need to read this separate page: \ref PassingByValue "Passing Eigen objects by value to functions".
+then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions".
-Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
+Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
\section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows)
@@ -91,13 +91,13 @@ void foo()
}
\endcode
-then you need to read this separate page: \ref WrongStackAlignment "Compiler making a wrong assumption on stack alignment".
+then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment".
-Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
+Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
\section explanation General explanation of this assertion
-\ref FixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash.
+\ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash.
Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".
diff --git a/doc/I00_CustomizingEigen.dox b/doc/I00_CustomizingEigen.dox
index cc4218f0c..fddd42348 100644
--- a/doc/I00_CustomizingEigen.dox
+++ b/doc/I00_CustomizingEigen.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page CustomizingEigen Advanced - Customizing/Extending Eigen
+/** \page TopicCustomizingEigen Customizing/Extending Eigen
Eigen can be extended in several ways, for instance, by defining global methods, \ref ExtendingMatrixBase "by adding custom methods to MatrixBase", adding support to \ref CustomScalarType "custom types" etc.
diff --git a/doc/I01_TopicLazyEvaluation.dox b/doc/I01_TopicLazyEvaluation.dox
index 68fa1e2df..393bc41d8 100644
--- a/doc/I01_TopicLazyEvaluation.dox
+++ b/doc/I01_TopicLazyEvaluation.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page TopicLazyEvaluation Advanced - Lazy Evaluation and Aliasing
+/** \page TopicLazyEvaluation Lazy Evaluation and Aliasing
Executive summary: Eigen has intelligent compile-time mechanisms to enable lazy evaluation and removing temporaries where appropriate.
It will handle aliasing automatically in most cases, for example with matrix products. The automatic behavior can be overridden
diff --git a/doc/I02_HiPerformance.dox b/doc/I02_HiPerformance.dox
index c2148ab4d..a7d271109 100644
--- a/doc/I02_HiPerformance.dox
+++ b/doc/I02_HiPerformance.dox
@@ -1,7 +1,7 @@
namespace Eigen {
-/** \page HiPerformance Advanced - Using Eigen with high performance
+/** \page TopicHiPerformance Using Eigen with high performance
In general achieving good performance with Eigen does no require any special effort:
simply write your expressions in the most high level way. This is especially true
diff --git a/doc/I03_InsideEigenExample.dox b/doc/I03_InsideEigenExample.dox
index 95cbe6800..e0f8d52a9 100644
--- a/doc/I03_InsideEigenExample.dox
+++ b/doc/I03_InsideEigenExample.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page InsideEigenExample Advanced - What happens inside Eigen, on a simple example
+/** \page TopicInsideEigenExample What happens inside Eigen, on a simple example
\b Table \b of \b contents
- \ref WhyInteresting
diff --git a/doc/I05_FixedSizeVectorizable.dox b/doc/I05_FixedSizeVectorizable.dox
index 9ec36898e..db8f10b5c 100644
--- a/doc/I05_FixedSizeVectorizable.dox
+++ b/doc/I05_FixedSizeVectorizable.dox
@@ -1,6 +1,6 @@
namespace Eigen {
-/** \page FixedSizeVectorizable Advanced - Fixed-size vectorizable Eigen objects
+/** \page TopicFixedSizeVectorizable Fixed-size vectorizable Eigen objects
The goal of this page is to explain what we mean by "fixed-size vectorizable".
diff --git a/doc/Overview.dox b/doc/Overview.dox
index e6f7349da..8bbdf1f1a 100644
--- a/doc/Overview.dox
+++ b/doc/Overview.dox
@@ -15,18 +15,33 @@ Eigen2 users: here is a \ref Eigen2ToEigen3 guide to help porting your applicati
For a first contact with Eigen, the best place is to have a look at the \ref GettingStarted "tutorial". The \ref QuickRefPage "short reference" page gives you a quite complete description of the API in a very condensed format that is specially useful to recall the syntax of a particular features, or to have a quick look at the API. For Matlab users, there is also a ASCII quick reference with Matlab translations.
\b Table \b of \b contents
+ - \ref Eigen2ToEigen3
- \ref GettingStarted
- \b Tutorial
- \ref TutorialMatrixClass
- \ref TutorialMatrixArithmetic
- \ref TutorialArrayClass
- \ref TutorialBlockOperations
- - "Dense linear algebra"
- - "Geometry"
- - "Reductions, visitors, and broadcasting"
- - "Sparse matrices"
+ - \ref TutorialAdvancedInitialization
+ - Comming soon: "Reductions, visitors, and broadcasting"
+ - \ref TutorialLinearAlgebra
+ - \ref TutorialGeometry
+ - \ref TutorialSparseMatrix
- \ref QuickRefPage
- - \ref Eigen2ToEigen3
+ - \b Advanced \b topics
+ - \ref TopicLazyEvaluation
+ - \ref TopicLinearAlgebraDecompositions
+ - \ref TopicCustomizingEigen
+ - \ref TopicInsideEigenExample
+ - \ref TopicHiPerformance
+ - Topics related to alignment issues
+ - \ref TopicUnalignedArrayAssert
+ - \ref TopicFixedSizeVectorizable
+ - \ref TopicStlContainers
+ - \ref TopicStructHavingEigenMembers
+ - \ref TopicPassingByValue
+ - \ref TopicWrongStackAlignment
+
Want more? Checkout the \ref Unsupported_modules "unsupported modules" documentation.