Changeset 9419

Timestamp:

Oct 29, 2012, 3:48:20 PM (12 years ago)

Author:

davidsa

Message:

Added documentation to orxonox::RenderQueueListener

Location:

code/branches/shaders/src/orxonox

Files:

• RenderQueueListener.cc (modified) (3 diffs)
• RenderQueueListener.h (modified) (2 diffs)

code/branches/shaders/src/orxonox/RenderQueueListener.cc

@@ -28 +28 @@
  */
 
+/**
+  @file RenderQueueListener.cc
+  @brief Definition of the RenderQueueListener class.
+*/
+
 #include "RenderQueueListener.h"
 
@@ -35 +40 @@
 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)
     {
@@ -56 +67 @@
         }
     }
-   
+    
+    /**
+    @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)
     {

code/branches/shaders/src/orxonox/RenderQueueListener.h

@@ -28 +28 @@
  */
 
+/**
+  @file RenderQueueListener.h
+  @brief Definition of the RenderQueueListener class.
+*/
+
 #ifndef _ORenderQueueListener_H__
 #define _ORenderQueueListener_H__
@@ -37 +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);
     };