[DOC] documentation and style changes

src/core/common/WPropertyTypes.h

@@ -640,7 +640,7 @@ namespace PROPERTY_TYPE_HELPER
         /**
          * Creates a string from the specified value.
          *
-         * \param v the value to convert
+         * \param tf the value to convert
          *
          * \return the string representation
          */

src/core/common/WTransferFunction.cpp

@@ -24,6 +24,12 @@
 
 #include <cassert>
 
+#include <iostream>
+#include <algorithm>
+
+//#include <osg/Vec4>
+//#include <osg/io_utils> // for the operator<< and operator>> for Vec4
+
 #include "WTransferFunction.h"
 
 bool WTransferFunction::operator==( const WTransferFunction &rhs ) const

src/core/common/WTransferFunction.h

@@ -25,13 +25,9 @@
 #ifndef WTRANSFERFUNCTION_H
 #define WTRANSFERFUNCTION_H
 
-#include <iostream>
 #include <vector>
-#include <algorithm>
 
 #include "WColor.h"
-#include <osg/Vec4>
-#include <osg/io_utils> // for the operator<< and operator>> for Vec4
 
 #include "WExportCommon.h"
 
@@ -41,176 +37,228 @@
  */
 class WTransferFunction
 {
-    private:
+private:
 
-        struct Entry
+    /**
+     * Prototype for a storage element
+     */
+    struct Entry
+    {
+        /**
+         * Default constructor
+         * \param iso the iso value
+         */
+        explicit Entry( double iso ) : iso( iso )
         {
-            explicit Entry( double iso ) : iso( iso )
-            {
-            }
+        }
 
-            bool operator <= ( const Entry &rhs ) const
-            {
-                return iso <= rhs.iso;
-            }
+        /**
+         * comparison by isovalue
+         * \param rhs entry to compare t
+         */
+        bool operator <= ( const Entry &rhs ) const
+        {
+            return iso <= rhs.iso;
+        }
 
-            double iso;
-        };
+        double iso; //< the isovalue
+    };
 
-        //typedef Entry LessPred;
-        struct ColorEntry : public Entry
+    /**
+     * Color entries are linearly interpolated colors along isovalues
+     */
+    struct ColorEntry : public Entry
     {
+        /** default constructor
+         * \param iso the isovalue
+         * \param color the color at the isovalue
+         */
         ColorEntry( double iso, WColor color ) : Entry( iso ), color( color )
         {
         }
 
+        /**
+         * comparison operator to check for changes
+         * \param rhs ColorEntry to compare to
+         */
         bool operator==( const ColorEntry& rhs ) const
         {
             return iso == rhs.iso && color == rhs.color;
         }
 
-        WColor color;
+        WColor color; //< holds the current color at isovalue Entry::iso
     };
 
-        struct AlphaEntry : public Entry
+    /**
+     * Alpha entries represent linearly interpolated transparency values
+     * along the isovalue scale. Alpha is in the range [ 0...1 ] where
+     * 1 signifies entirely opaque ( which makes it more an opacity value instead
+     * of alpha, but I use the commonly used language here )
+     */
+    struct AlphaEntry : public Entry
     {
-        AlphaEntry( double iso, double alpha ) : Entry( iso ), alpha( alpha )
+        /** default constructor
+         * \param iso the isovalue
+         * \param alpha the alpha at the isovalue in the range from 0 = transparent to 1 = opaque
+         */
+         AlphaEntry( double iso, double alpha ) : Entry( iso ), alpha( alpha )
         {
         }
 
+        /**
+         * comparison operator to check for changes
+         * \param rhs AlphaEntry to compare to
+         */
         bool operator==( const AlphaEntry& rhs ) const
         {
             return iso == rhs.iso && alpha == rhs.alpha;
         }
 
-        double alpha;
+        double alpha; //< holds the current alpha at isovalue Entry::iso
     };
 
-        template<typename T>
-            struct LessPred
+    /**
+     * Templatized comparison predicate for internal searching
+     */
+    template<typename T>
+        struct LessPred
+        {
+            explicit LessPred( double iso ) : iso( iso )
             {
-                explicit LessPred( double iso ) : iso( iso )
-                {
-                }
+            }
 
-                bool operator()( const T& t )
-                {
-                    return iso < t.iso;
-                }
+            /** isovalue-based comparison */
+            bool operator()( const T& t )
+            {
+                return iso < t.iso;
+            }
 
-                double iso;
-            };
+            double iso; //< the isovalue to compare to
+        };
 
-    public:
-        WTransferFunction() : isomin( 0. ), isomax( 0. )
+public:
+    /** default constructor of a meaningless transfer function */
+    WTransferFunction() : isomin( 0. ), isomax( 0. )
     {
     }
 
-        WTransferFunction( const WTransferFunction &rhs )
-            : colors( rhs.colors ), alphas( rhs.alphas ), isomin( rhs.isomin ), isomax( rhs.isomax ), histogram( rhs.histogram )
-        {
-        }
-
-        WTransferFunction& operator=( const WTransferFunction &rhs )
-        {
-            this->colors = rhs.colors;
-            this->alphas = rhs.alphas;
-            this->isomin = rhs.isomin;
-            this->isomax = rhs.isomax;
-            this->histogram = rhs.histogram;
-            return ( *this );
-        }
-
-        bool operator==( const WTransferFunction &rhs ) const;
+    /** deep copy constructor */
+    WTransferFunction( const WTransferFunction &rhs )
+        : colors( rhs.colors ), alphas( rhs.alphas ), isomin( rhs.isomin ), isomax( rhs.isomax ), histogram( rhs.histogram )
+    {
+    }
 
-        bool operator!=( const WTransferFunction &rhs ) const;
+    /** deep copy operator */
+    WTransferFunction& operator=( const WTransferFunction &rhs )
+    {
+        this->colors = rhs.colors;
+        this->alphas = rhs.alphas;
+        this->isomin = rhs.isomin;
+        this->isomax = rhs.isomax;
+        this->histogram = rhs.histogram;
+        return ( *this );
+    }
 
-        ~WTransferFunction()
-        {
-        }
+    /**
+     * \returns true if this object contains exactly the same
+     * data as rhs
+     * \param rhs object to compare with
+     */
+    bool operator==( const WTransferFunction &rhs ) const;
 
-        size_t numAlphas() const
-        {
-            return alphas.size();
-        }
+    /**
+     * \returns negated result of operator==
+     */
+    bool operator!=( const WTransferFunction &rhs ) const;
 
-        size_t numColors() const
-        {
-            return colors.size();
-        }
+    /** default destuctor */
+    ~WTransferFunction()
+    {
+    }
 
-        double getAlphaIsovalue( size_t i ) const
-        {
-            return alphas.at( i ).iso;
-        }
+    size_t numAlphas() const
+    {
+        return alphas.size();
+    }
 
-        double getColorIsovalue( size_t i ) const
-        {
-            return colors.at( i ).iso;
-        }
+    size_t numColors() const
+    {
+        return colors.size();
+    }
 
-        double getAlpha( size_t i ) const
-        {
-            return alphas.at( i ).alpha;
-        }
+    double getAlphaIsovalue( size_t i ) const
+    {
+        return alphas.at( i ).iso;
+    }
 
-        const WColor& getColor( size_t i ) const
-        {
-            return colors.at( i ).color;
-        }
+    double getColorIsovalue( size_t i ) const
+    {
+        return colors.at( i ).iso;
+    }
 
-        /**
-         * insert a new color point
-         */
-        void addColor( double iso, const WColor& color );
+    double getAlpha( size_t i ) const
+    {
+        return alphas.at( i ).alpha;
+    }
 
-        /**
-         * insert a new alpha point
-         */
-        void addAlpha( double iso, double alpha );
+    const WColor& getColor( size_t i ) const
+    {
+        return colors.at( i ).color;
+    }
 
-        /**
-         * set the histogram going along with the transfer function
-         *
-         * This should be changed in the future to be handled in a different
-         * way. A good option would be to introduce an object encapsulating
-         * a transfer function and histogram information.
-         */
-        void setHistogram( std::vector< double > & data )
-        {
-            histogram.swap( data );
-        }
+    /**
+     * insert a new color point
+     */
+    void addColor( double iso, const WColor& color );
+
+    /**
+     * insert a new alpha point
+     */
+    void addAlpha( double iso, double alpha );
+
+    /**
+     * set the histogram going along with the transfer function
+     *
+     * This should be changed in the future to be handled in a different
+     * way. A good option would be to introduce an object encapsulating
+     * a transfer function and histogram information.
+     */
+    void setHistogram( std::vector< double > & data )
+    {
+        histogram.swap( data );
+    }
 
-        /**
-         * clears the histogram data so the gui won't show any
-         */
-        void removeHistogram()
-        {
-            histogram.clear();
-        }
+    /**
+     * clears the histogram data so the gui won't show any
+     */
+    void removeHistogram()
+    {
+        histogram.clear();
+    }
 
-        const std::vector< double >& getHistogram() const
-        {
-            return histogram;
-        }
+    const std::vector< double >& getHistogram() const
+    {
+        return histogram;
+    }
 
-        /**
-         * sample/render the transfer function linearly between min and max in an RGBA texture.
-         * \param width is the number of RGBA samples.
-         * \param min the lowest value to be sampled
-         * \param max the hightes value to be sampled
-         * \post array contains the sampled data
-         */
-        void sample1DTransferFunction( unsigned char*array, int width, double min, double max ) const;
-    private:
+    /**
+     * sample/render the transfer function linearly between min and max in an RGBA texture.
+     * \param width is the number of RGBA samples.
+     * \param min the lowest value to be sampled
+     * \param max the hightes value to be sampled
+     * \post array contains the sampled data
+     */
+    void sample1DTransferFunction( unsigned char*array, int width, double min, double max ) const;
+private:
 
-        std::vector<ColorEntry> colors;
-        std::vector<AlphaEntry> alphas;
+    std::vector<ColorEntry> colors; //< sorted list of colors
+    std::vector<AlphaEntry> alphas; //< sorted list of alpha values
 
-        double isomin;
-        double isomax;
+    double isomin; //< smallest iso value
+    double isomax; //< largest iso value
 
-        std::vector< double > histogram;
+    std::vector< double > histogram; //< store a histogram. This is used for property-handling only
+                                     // and does not change the transfer function at all.
 };
 
 #endif  // WTRANSFERFUNCTION_H