Update documentation.

git-svn-id: svn://svn.code.sf.net/p/irrlicht/code/trunk@5066 dfc29bdd-3216-0410-991c-e03cc46cb475

include/quaternion.h

@@ -10,10 +10,15 @@
 #include "matrix4.h"
 #include "vector3d.h"
 
-// Between Irrlicht 1.7 and Irrlicht 1.8 the quaternion-matrix conversions got fixed.
-// This define disables all involved functions completely to allow finding all places
-// where the wrong conversions had been in use.
-#define IRR_TEST_BROKEN_QUATERNION_USE 0
+// NOTE: You *only* need this when updating an application from Irrlicht before 1.8 to Irrlicht 1.8 or later.
+// Between Irrlicht 1.7 and Irrlicht 1.8 the quaternion-matrix conversions changed.
+// Before the fix they had mixed left- and right-handed rotations.
+// To test if your code was affected by the change enable IRR_TEST_BROKEN_QUATERNION_USE and try to compile your application.
+// This defines removes those functions so you get compile errors anywhere you use them in your code.
+// For every line with a compile-errors you have to change the corresponding lines like that:
+// - When you pass the matrix to the quaternion constructor then replace the matrix by the transposed matrix.
+// - For uses of getMatrix() you have to use quaternion::getMatrix_transposed instead.
+// #define IRR_TEST_BROKEN_QUATERNION_USE
 
 namespace irr
 {
@@ -39,7 +44,7 @@ class quaternion
 		//! Constructor which converts euler angles (radians) to a quaternion
 		quaternion(const vector3df& vec);
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 		//! Constructor which converts a matrix to a quaternion
 		quaternion(const matrix4& mat);
 #endif
@@ -53,7 +58,7 @@ class quaternion
 		//! Assignment operator
 		inline quaternion& operator=(const quaternion& other);
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 		//! Matrix assignment operator
 		inline quaternion& operator=(const matrix4& other);
 #endif
@@ -98,7 +103,7 @@ class quaternion
 		//! Normalizes the quaternion
 		inline quaternion& normalize();
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 		//! Creates a matrix from this quaternion
 		matrix4 getMatrix() const;
 #endif
@@ -196,7 +201,7 @@ inline quaternion::quaternion(const vector3df& vec)
 	set(vec.X,vec.Y,vec.Z);
 }
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 // Constructor which converts a matrix to a quaternion
 inline quaternion::quaternion(const matrix4& mat)
 {
@@ -229,7 +234,7 @@ inline quaternion& quaternion::operator=(const quaternion& other)
 	return *this;
 }
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 // matrix assignment operator
 inline quaternion& quaternion::operator=(const matrix4& m)
 {
@@ -333,7 +338,7 @@ inline quaternion quaternion::operator+(const quaternion& b) const
 	return quaternion(X+b.X, Y+b.Y, Z+b.Z, W+b.W);
 }
 
-#if !IRR_TEST_BROKEN_QUATERNION_USE
+#ifndef IRR_TEST_BROKEN_QUATERNION_USE
 // Creates a matrix from this quaternion
 inline matrix4 quaternion::getMatrix() const
 {