muuuch improved documentation for the unaligned array assert.

also split into several pages for better reusability (more generally useful than
just for this assert)

1 files changed, 36 insertions, 0 deletions

diff --git a/doc/FixedSizeVectorizable.dox b/doc/FixedSizeVectorizable.dox
new file mode 100644
index 000000000..f53a6ef02
--- /dev/null
+++ b/doc/FixedSizeVectorizable.dox
@@ -0,0 +1,36 @@
+namespace Eigen {
+
+/** \page FixedSizeVectorizable Fixed-size vectorizable Eigen objects
+
+The goal of this page is to explain what we mean by "fixed-size vectorizable".
+
+\section summary Executive Summary
+
+An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes.
+
+Examples include:
+\li Eigen::Vector2d
+\li Eigen::Vector4d
+\li Eigen::Vector4f
+\li Eigen::Matrix2d
+\li Eigen::Matrix2f
+\li Eigen::Matrix4d
+\li Eigen::Matrix4f
+\li Eigen::Transform3d
+\li Eigen::Transform3f
+
+\section explanation Explanation
+
+First, "fixed-size" should be clear: an Eigen object has fixed size if its number of rows and its number of columns are fixed at compile-time. So for example Matrix3f has fixed size, but MatrixXf doesn't (the opposite of fixed-size is dynamic-size).
+
+The array of coefficients of a fixed-size Eigen object is a plain "static array", it is not dynamically allocated. For example, the data behind a Matrix4f is just a "float array[16]".
+
+Fixed-size objects are typically very small, which means that we want to handle them with zero runtime overhead -- both in terms of memory usage and of speed.
+
+Now, vectorization (both SSE and AltiVec) works with 128-bit packets. Moreover, for performance reasons, these packets need to be have 128-bit alignment.
+
+So it turns out that the only way that fixed-size Eigen objects can be vectorized, is if their size is a multiple of 128 bits, or 16 bytes. Eigen will then request 16-byte alignment for these object, and henceforth rely on these objects being aligned so no runtime check for alignment is performed.
+
+*/
+
+}