Merge pull request #482 from hwiesmann/master

Addition of comments for ClusterCullingCallback

include/osg/ClusterCullingCallback

@@ -19,8 +19,31 @@
 
 namespace osg {
 
-/** Implements cluster culling to cull back facing drawables. Derived from
-  * Drawable::CullCallback.
+/** @class ClusterCullingCallback 
+    @brief Implements cluster culling to cull back facing subgraphs and drawables. Derived from Drawable::CullCallback and osg::NodeCallback.
+    
+    This culling callback is intended to be attached to a node using the setCullCallback method. If the
+    node is a drawable cull(osg::NodeVisitor*, osg::Drawable*, osg::State*) otherwise
+    operator()(Node*, NodeVisitor*) will be called during the cull traversal.
+    
+    To decide whether the node (in case of a drawable) or its children (in case of any other node type) are
+    to be culled depends on four parameters:
+     - a control point,
+     - a normal specified at the control point,
+     - a deviation value representing the cosinus of an enclosed angle and
+     - a radius describing a sphere around the control point.
+    
+    The node is culled if the following two conditions are fulfilled:
+     - the distance between the current eye/view point to the control point is larger or equal to radius,
+     - the cosinus of the enclosed angle between the normal and the vector from the control point to the eye/view point
+       is smaller(!) than the specified deviation value (normally this value is negative meaning that the enclosed angle
+       between the control point and the eye/view point is larger than the angle indirectly specified by the
+       deviation value).
+    
+    @remark As the deviation is representing the cosine of an enclosed angle its value should be within the
+            the interval [-1; 1]. A value of one will cull all nodes while a value of -1 will never cull a node.
+            The deviation will normally have negative values because then the enclosed angle between the normal and the
+            eye/view point is larger than 90 degrees (and therefore the eye sees the "back" from the control point).
 */
 class OSG_EXPORT ClusterCullingCallback : public DrawableCullCallback, public NodeCallback
 {