FixedSizeVectorizable.dox (1906B)
1 namespace Eigen { 2 3 /** \eigenManualPage TopicFixedSizeVectorizable Fixed-size vectorizable %Eigen objects 4 5 The goal of this page is to explain what we mean by "fixed-size vectorizable". 6 7 \section FixedSizeVectorizable_summary Executive Summary 8 9 An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes. 10 11 Examples include: 12 \li Eigen::Vector2d 13 \li Eigen::Vector4d 14 \li Eigen::Vector4f 15 \li Eigen::Matrix2d 16 \li Eigen::Matrix2f 17 \li Eigen::Matrix4d 18 \li Eigen::Matrix4f 19 \li Eigen::Affine3d 20 \li Eigen::Affine3f 21 \li Eigen::Quaterniond 22 \li Eigen::Quaternionf 23 24 \section FixedSizeVectorizable_explanation Explanation 25 26 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 \ref Matrix3f has fixed size, but \ref MatrixXf doesn't (the opposite of fixed-size is dynamic-size). 27 28 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 \ref Matrix4f is just a "float array[16]". 29 30 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. 31 32 Now, vectorization works with 128-bit packets (e.g., SSE, AltiVec, NEON), 256-bit packets (e.g., AVX), or 512-bit packets (e.g., AVX512). Moreover, for performance reasons, these packets are most efficiently read and written if they have the same alignment as the packet size, that is 16 bytes, 32 bytes, and 64 bytes respectively. 33 34 So it turns out that the best way that fixed-size %Eigen objects can be vectorized, is if their size is a multiple of 16 bytes (or more). %Eigen will then request 16-byte alignment (or more) for these objects, and henceforth rely on these objects being aligned to achieve maximal efficiency. 35 36 */ 37 38 }