[Orxonox-commit 4750] r9419 - code/branches/shaders/src/orxonox

[davidsa at orxonox.net]

Author: davidsa
Date: 2012-10-29 15:48:20 +0100 (Mon, 29 Oct 2012)
New Revision: 9419

Modified:
   code/branches/shaders/src/orxonox/RenderQueueListener.cc
   code/branches/shaders/src/orxonox/RenderQueueListener.h
Log:
Added documentation to orxonox::RenderQueueListener

Modified: code/branches/shaders/src/orxonox/RenderQueueListener.cc
===================================================================
--- code/branches/shaders/src/orxonox/RenderQueueListener.cc	2012-10-29 14:46:26 UTC (rev 9418)
+++ code/branches/shaders/src/orxonox/RenderQueueListener.cc	2012-10-29 14:48:20 UTC (rev 9419)
@@ -27,6 +27,11 @@
  *
  */
 
+/**
+  @file RenderQueueListener.cc
+  @brief Definition of the RenderQueueListener class.
+*/
+
 #include "RenderQueueListener.h"
 
 #include <OgreRoot.h>
@@ -34,6 +39,12 @@
 
 namespace orxonox
 {
+    /**
+    @brief
+    This function is called just before a RenderQueueGroup is rendered, this function is called by Ogre automatically with the correct parameters.
+
+    In this case we use it to set the stencil buffer parameters of the render system
+    */
     void RenderQueueListener::renderQueueStarted(Ogre::uint8 queueGroupId, const Ogre::String& invocation, bool& skipThisInvocation)
     {
         if (queueGroupId == RENDER_QUEUE_STENCIL_OBJECTS)
@@ -55,7 +66,13 @@
                   Ogre::SOP_KEEP,Ogre::SOP_KEEP,Ogre::SOP_REPLACE,false);       
         }
     }
-   
+    
+    /**
+    @brief
+        This function is called just after a RenderQueueGroup has been rendered, this function is called by Ogre automatically with the correct parameters.
+        
+        in this case we use it to unset the stencil buffer parameters, so the rest of the render queue is unaffected by it.
+    */
     void RenderQueueListener::renderQueueEnded(Ogre::uint8 queueGroupId, const Ogre::String& invocation, bool& repeatThisInvocation)
     {
         if (queueGroupId == RENDER_QUEUE_STENCIL_LAST) 

Modified: code/branches/shaders/src/orxonox/RenderQueueListener.h
===================================================================
--- code/branches/shaders/src/orxonox/RenderQueueListener.h	2012-10-29 14:46:26 UTC (rev 9418)
+++ code/branches/shaders/src/orxonox/RenderQueueListener.h	2012-10-29 14:48:20 UTC (rev 9419)
@@ -27,6 +27,11 @@
  *
  */
 
+/**
+  @file RenderQueueListener.h
+  @brief Definition of the RenderQueueListener class.
+*/
+
 #ifndef _ORenderQueueListener_H__
 #define _ORenderQueueListener_H__
 
@@ -36,23 +41,42 @@
 
 namespace orxonox
 {
-    /* Defining some render queue groups based around the main render queue to enable a stenicl buffer based glow effect */
-    enum RenderQueueGroupID
+    enum RenderQueueGroupID //!< these are IDs for render queues that are executed just after the main render queue defined by Ogre, we need more than one for Stencil Glow
     {
-        RENDER_QUEUE_MAIN = Ogre::RENDER_QUEUE_MAIN,
+        RENDER_QUEUE_MAIN = Ogre::RENDER_QUEUE_MAIN, //reference to the main render queue
         RENDER_QUEUE_STENCIL_OBJECTS = RENDER_QUEUE_MAIN+1,
         RENDER_QUEUE_STENCIL_GLOW = RENDER_QUEUE_MAIN+2,
-        RENDER_QUEUE_STENCIL_LAST = RENDER_QUEUE_STENCIL_GLOW
+        RENDER_QUEUE_STENCIL_LAST = RENDER_QUEUE_STENCIL_GLOW //this is a reference to the last render queue to be affected by stencil glow effects
     };
 
-    const int STENCIL_VALUE_FOR_GLOW = 1; //if more than one type of stencil mask is to be used it needs to use another value
-    const int STENCIL_FULL_MASK = 0xFFFFFFFF;
+    const int STENCIL_VALUE_FOR_GLOW = 1; //!< this is a reference value for our mask, 
+                                          //!< if more than one type of stencil mask is to be used, each of them need their own value
+    const int STENCIL_FULL_MASK = 0xFFFFFFFF; //!< this is a reference mask used in our stencil buffer
     
-    /* Deriving from the Ogre RenderQueueListener to define our own handling of the different rendering stages to enable alpha based shader/glow effects */
+    /**
+    @brief
+        This class derives from the Ogre-Class RenderQueueListener and provides a way to define new rendering stages to enable use of e.g. stencil buffers
+        to increase the number of shader effects we can create. Especially important for shader-based alpha blending.
+
+    @author
+        David 'davidsa' Salvisberg
+    */
     class _OrxonoxExport RenderQueueListener : public Ogre::RenderQueueListener
     {
         public:
+            /**
+            @brief
+                This function is called just before a RenderQueueGroup is rendered, this function is called by Ogre automatically with the correct parameters.
+                
+                In this case we use it to set the stencil buffer parameters of the render system
+            */
             virtual void renderQueueStarted(Ogre::uint8 queueGroupId, const Ogre::String& invocation, bool& skipThisInvocation);
+            /**
+            @brief
+                This function is called just after a RenderQueueGroup has been rendered, this function is called by Ogre automatically with the correct parameters.
+                
+                in this case we use it to unset the stencil buffer parameters, so the rest of the render queue is unaffected by it.
+            */
             virtual void renderQueueEnded(Ogre::uint8 queueGroupId, const Ogre::String& invocation, bool& repeatThisInvocation);
     };
 }