unless i find more failures in the tests, this will be beta3...

* fixes for mistakes (especially in the cast() methods in Geometry) revealed by the new "mixing types" test
* dox love, including a section on coeff access in core and an overview in geometry

3 files changed, 40 insertions, 1 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index c3a6a9ddb..a781d39d1 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -1193,7 +1193,8 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = EIGEN_EMPTY_STRUCT \
                          EIGEN_PARSED_BY_DOXYGEN \
                          EIGEN_VECTORIZE \
-                         EIGEN_QT_SUPPORT
+                         EIGEN_QT_SUPPORT \
+                         EIGEN_STRONG_INLINE=inline
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
diff --git a/doc/QuickStartGuide.dox b/doc/QuickStartGuide.dox
index 81df4aa3d..446bade0c 100644
--- a/doc/QuickStartGuide.dox
+++ b/doc/QuickStartGuide.dox
@@ -14,6 +14,7 @@ namespace Eigen {
   - \ref TutorialCoreSimpleExampleFixedSize
   - \ref TutorialCoreSimpleExampleDynamicSize
   - \ref TutorialCoreMatrixTypes
+  - \ref TutorialCoreCoefficients
   - \ref TutorialCoreMatrixInitialization
   - \ref TutorialCoreArithmeticOperators
   - \ref TutorialCoreReductions
@@ -87,8 +88,23 @@ For example, \c Vector3d is a typedef for \code Matrix<double, 3, 1> \endcode
 For dynamic-size, that is in order to left the number of rows or of columns unspecified at compile-time, use the special value Eigen::Dynamic. For example, \c VectorXd is a typedef for \code Matrix<double, Dynamic, 1> \endcode
 
 
+<a href="#" class="top">top</a>\section TutorialCoreCoefficients Coefficient access
 
+Eigen supports the following syntaxes for read and write coefficient access:
 
+\code
+matrix(i,j);
+vector(i)
+vector[i]
+vector.x() // first coefficient
+vector.y() // second coefficient
+vector.z() // third coefficient
+vector.w() // fourth coefficient
+\endcode
+
+Notice that these coefficient access methods have assertions checking the ranges. So if you do a lot of coefficient access, these assertion can have an important cost. There are then two possibilities if you want avoid paying this cost:
+\li Either you can disable assertions altogether, by defining EIGEN_NO_DEBUG or NDEBUG. Notice that some IDEs like MS Visual Studio define NDEBUG automatically in "Release Mode".
+\li Or you can disable the checks on a case-by-case basis by using the coeff() and coeffRef() methods: see MatrixBase::coeff(int,int) const, MatrixBase::coeffRef(int,int), etc.
 
 <a href="#" class="top">top</a>\section TutorialCoreMatrixInitialization Matrix and vector creation and initialization
 
diff --git a/doc/TutorialGeometry.dox b/doc/TutorialGeometry.dox
index 5a1a3e06e..b30499763 100644
--- a/doc/TutorialGeometry.dox
+++ b/doc/TutorialGeometry.dox
@@ -18,6 +18,28 @@ namely 2D and 3D rotations and affine transformations.
   - \ref TutorialGeoTransform
   - \ref TutorialGeoEulerAngles
 
+Eigen's Geometry module provides two different kinds of geometric transformations:
+  - Abstract transformations, such as rotations (represented by \ref AngleAxis "angle and axis" or by a \ref Quaternion "quaternion"), \ref Translation "translations", \ref Scaling "scalings". These transformations are NOT represented as matrices, but you can nevertheless mix them with matrices and vectors in expressions, and convert them to matrices if you wish.
+  - Affine transformation matrices: see the Transform class. These are really matrices.
+
+\note If you are working with OpenGL 4x4 matrices then Transform3f and Transform3d are what you want. Since Eigen defaults to column-major storage, you can directly use the Transform::data() method to pass your transformation matrix to OpenGL.
+
+You can construct a Transform from an abstract transformation, like this:
+\code
+  Transform t(AngleAxis(angle,axis));
+\endcode
+or like this:
+\code
+  Transform t;
+  t = AngleAxis(angle,axis);
+\endcode
+But note that unfortunately, because of how C++ works, you can \b not do this:
+\code
+  Transform t = AngleAxis(angle,axis);
+\endcode
+<span class="note">\b Explanation: In the C++ language, this would require Transform to have a non-explicit conversion constructor from AngleAxis, but we really don't want to allow implicit casting here.
+</span>
+
 \section TutorialGeoElementaryTransformations Transformation types
 
 <table class="tutorial_code">