Changeset 11450

Timestamp:

05/20/10 19:02:45 (2 years ago)

Author:

robert

Message:

From Hartwig Wiesmann, "I have added some doxygen documentation to the plane class.
"

Files:

• OpenSceneGraph/trunk/include/osg/Plane (modified) (7 diffs)

OpenSceneGraph/trunk/include/osg/Plane

@@ -27 +27 @@
 namespace osg {
 
-/** A plane class. It can be used to represent an infinite plane.*/
+/** @brief A plane class. It can be used to represent an infinite plane.
+  * 
+  * The infinite plane is described by an implicit plane equation a*x+b*y+c*z+d = 0. Though it is not mandatory that
+  * a^2+b^2+c^2 = 1 is fulfilled in general some methods require it (@see osg::Plane::distance). */
 class OSG_EXPORT Plane
 {
@@ -49 +52 @@
 
 
+        /// Default constructor
+        /** The default constructor initializes all values to zero.
+          * @warning Although the method osg::Plane::valid() will return true after the default constructors call the plane
+          *          is mathematically invalid! Default data do not describe a valid plane. */
         inline Plane() { _fv[0]=0.0; _fv[1]=0.0; _fv[2]=0.0; _fv[3]=0.0; _lowerBBCorner = 0; _upperBBCorner = 0; }
         inline Plane(const Plane& pl) { set(pl); }
+        /// Constructor
+        /** The plane is described as a*x+b*y+c*z+d = 0.
+          * @remark You may call osg::Plane::MakeUnitLength afterwards if the passed values are not normalized. */
         inline Plane(value_type a,value_type b,value_type c,value_type d) { set(a,b,c,d); }
 
+        /// Constructor
+        /** The plane can also be described as vec*[x,y,z,1].
+          * @remark You may call osg::Plane::MakeUnitLength afterwards if the passed values are not normalized. */
         inline Plane(const Vec4f& vec) { set(vec); }
+        /// Constructor
+        /** The plane can also be described as vec*[x,y,z,1].
+          * @remark You may call osg::Plane::MakeUnitLength afterwards if the passed values are not normalized. */
         inline Plane(const Vec4d& vec) { set(vec); }
 
+        /// Constructor
+        /** This constructor initializes the internal values directly without any checking or manipulation.
+          * @param norm The normal of the plane.
+          * @param d    The negative distance from the point of origin to the plane.
+          * @remark You may call osg::Plane::MakeUnitLength afterwards if the passed normal was not normalized. */
         inline Plane(const Vec3_type& norm,value_type d) { set(norm,d); }
 
+        /// Constructor
+        /** This constructor calculates from the three points describing an infinite plane the internal values.
+          * @param v1 Point in the plane.
+          * @param v2 Point in the plane.
+          * @param v3 Point in the plane.
+          * @remark After this constructor call the plane's normal is normalized in case the three points described a mathematically
+          *         valid plane.
+          * @remark The normal is determined by building the cross product of (v2-v1) ^ (v3-v2). */
         inline Plane(const Vec3_type& v1, const Vec3_type& v2, const Vec3_type& v3) { set(v1,v2,v3); }
 
+        /// Constructor
+        /** This constructor initializes the internal values directly without any checking or manipulation.
+          * @param norm  The normal of the plane.
+          * @param point A point of the plane.
+          * @remark You may call osg::Plane::MakeUnitLength afterwards if the passed normal was not normalized. */
         inline Plane(const Vec3_type& norm, const Vec3_type& point) { set(norm,point); }
 
@@ -102 +136 @@
         }
 
-
+        /** This method multiplies the coefficients of the plane equation with a constant factor so that the
+          * equation a^2+b^2+c^2 = 1 holds. */
         inline void makeUnitLength()
         {
@@ -124 +159 @@
         }
 
+        /// Checks if all internal values describing the plane have valid numbers
+        /** @warning This method does not check if the plane is mathematically correctly described!
+          * @remark  The only case where all elements have valid numbers and the plane description is invalid occurs if the plane's normal
+          *          is zero. */
         inline bool valid() const { return !isNaN(); }
         inline bool isNaN() const { return osg::isNaN(_fv[0]) || osg::isNaN(_fv[1]) || osg::isNaN(_fv[2]) || osg::isNaN(_fv[3]); }
@@ -131 +170 @@
         inline bool operator != (const Plane& plane) const { return _fv[0]!=plane._fv[0] || _fv[1]!=plane._fv[1] || _fv[2]!=plane._fv[2] || _fv[3]!=plane._fv[3]; }
 
+        /** A plane is said to be smaller than another plane if the first non-identical element of the internal array is smaller than the
+          * corresponding element of the other plane. */
         inline bool operator <  (const Plane& plane) const
         {
@@ -154 +195 @@
         inline Vec3_type getNormal() const { return Vec3_type(_fv[0],_fv[1],_fv[2]); }
       
-        /** calculate the distance between a point and the plane.*/
+        /** Calculate the distance between a point and the plane.
+          * @remark This method only leads to real distance values if the plane's norm is 1.
+          * @sa osg::Plane::makeUnitLength */
         inline float distance(const osg::Vec3f& v) const
         {
@@ -162 +205 @@
                    _fv[3];
         }
-
+        /** Calculate the distance between a point and the plane.
+          * @remark This method only leads to real distance values if the plane's norm is 1.
+          * @sa osg::Plane::makeUnitLength */
         inline double distance(const osg::Vec3d& v) const
         {