Documented Render.h

include/Render.h

@@ -1,24 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file include/Render.h
+ * \brief OpenRaider Renderer class
  *
- * Project : Render
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Render
- * License : No use w/o permission (C) 2001 Mongoose
- * Comments: This is the renderer class for OpenRaider
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2001.05.21:
- * Mongoose - Created
- ================================================================*/
-
+ * \author Mongoose
+ */
 
 #ifndef _RENDER_H_
 #define _RENDER_H_
@@ -39,20 +24,33 @@
 #include <Emitter.h>
 #endif
 
-
+/*!
+ * \brief RenderRoom used by Renderer
+ */
 class RenderRoom {
 public:
+
+    /*!
+     * \brief Constructs an object of RenderRoom
+     */
     RenderRoom() {
         room = 0x0;
         dist = 0.0f;
         center[0] = center[1] = center[2] = 0.0f;
     }
 
+    /*!
+     * \brief Deconstructs an object of RenderRoom
+     */
     ~RenderRoom() {
         //! \fixme Hangs when erasing - might be shared pointers somewhere
         //lights.erase();
     }
 
+    /*!
+     * \brief Computes central point of room.
+     * Result is stored in center member variable.
+     */
     void computeCenter() {
         if (room)
             helMidpoint3v(room->bbox_min, room->bbox_max, center);
@@ -60,15 +58,18 @@ public:
 
     vec_t dist;             //!< Distance to near plane, move to room?
     vec3_t center;          //!< Center of bbox, move to room?
-    room_mesh_t *room;      //!< Physical room stored in World, very dangerous as allocated and used
     Vector<Light *> lights; //!< List of lights in this room
     Mesh mesh;              //!< OpenGL mesh that represents this room
-};
 
+    //! \fixme very dangerous as allocated and used
+    room_mesh_t *room;      //!< Physical room stored in World
+};
 
-class Render
-{
- public:
+/*!
+ * \brief OpenRaider Renderer class
+ */
+class Render {
+public:
 
     typedef enum {
         modeDisabled,
@@ -103,469 +104,251 @@ class Render
         skeletalMesh
     } RenderMeshType;
 
-    ////////////////////////////////////////////////////////////
-    // Constructors
-    ////////////////////////////////////////////////////////////
-
+    /*!
+     * \brief Constructs an object of Render
+     */
     Render();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Constructs an object of Render
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.21:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Deconstructs an object of Render
+     */
     ~Render();
-    /*------------------------------------------------------
-     * Pre  : Render object is allocated
-     * Post : Deconstructs an object of Render
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.21:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Public Accessors
-    ////////////////////////////////////////////////////////////
 
+    /*!
+     * \brief Makes a screenshot, writes to disk
+     * \param filenameBase basename of file to be written
+     */
     void screenShot(char *filenameBase);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Makes a screenshot, writes to disk as file
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.20:
-     * Mongoose - Created, factored out of OpenRaider class
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Gets current rendering mode
+     * \returns current RenderMode
+     * \fixme Don't return enum as int?!
+     */
     int getMode();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Gets current rendering mode
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.21:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Public Mutators
-    ////////////////////////////////////////////////////////////
 
     void addRoom(RenderRoom *rRoom);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post :
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.21:
-     * Mongoose - Created, factored out of World
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Starts and sets up OpenGL target
+     * \param width width of window
+     * \param height height of window
+     */
     void Init(int width, int height);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Starts and sets up OpenGL target
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.21:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Loads textures in a certain id slot
+     * \param image Image to load
+     * \param width width of image
+     * \param height height of image
+     * \param id id for texture
+     * \sa Texture::loadBufferSlot()
+     */
     void loadTexture(unsigned char *image,
                           unsigned int width, unsigned int height,
                           unsigned int id);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Loads textures in a certian id slot
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.20:
-     * Mongoose - Created, factored out of OpenRaider class
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sets up textures for OpenRaider.
+     * \param textureDir Is valid and exists with textures
+     * \param numLoaded returns number of loaded textures and will update
+     * number of external textures loaded
+     * \param nextId will update next level texture id
+     */
     void initTextures(char *textureDir, unsigned int *numLoaded,
                             unsigned int *nextId);
-    /*------------------------------------------------------
-     * Pre  : textureDir is valid and exists with textures
-     * Post : Sets up textures for OpenRaider
-     *        Returns number of loaded textures and
-     *
-     *        numLoaded will update number of
-     *        external textures loaded
-     *
-     *        nextId will update next level texture id
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.20:
-     * Mongoose - Created, factored out of OpenRaider class
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Initializes Emitter.
+     *
+     * Emitter is set up for rendering with 2 textures in
+     * a overhead rain or snow like pattern.
+     * Textures have to be initialized!
+     * \param name valid C-String name
+     * \param size valid size
+     * \param snowTex1 valid first texture
+     * \param snowTex2 valid second texture
+     */
     void initEmitter(const char *name, unsigned int size,
                           unsigned int snowTex1, unsigned int snowTex2);
-    /*------------------------------------------------------
-     * Pre  : Textures are init and these args are valid
-     * Post : Emitter is set up for rendering with 2 textures
-     *        in a overhead rain or snow like pattern
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.20:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * Removes current world/entity/etc geometry
+     */
     void ClearWorld();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Removes current world/entity/etc geometery
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-    void toggleFlag(unsigned int flag);
+
+    /*!
+     * \brief Clears bitflags, changes state of renderer in some way
+     * \param flags RenderFlags to clear (ORed)
+     * \fixme use enum not integer as parameter?!
+     */
     void clearFlags(unsigned int flags);
+
+    /*!
+     * \brief Sets bitflags, changes state of renderer in some way
+     * \param flags RenderFlags to set (ORed)
+     * \fixme use enum not integer as parameter?!
+     */
     void setFlags(unsigned int flags);
-  /*------------------------------------------------------
-   * Pre  : (Un)Sets bitflags for various control use
-   * Post : Changes state of renderer in some way
-   *
-   *-- History ------------------------------------------
-   *
-   * 2002.03.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
     void setMode(int n);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
     void Update(int width, int height);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders a single game frame
+     */
     void Display();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Renders a single game frame
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
     void setSkyMesh(int index, bool rot);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
     void ViewModel(entity_t *ent, int index);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
     void RegisterCamera(Camera *camera);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.05.21:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-   GLString *GetString();
-   /*------------------------------------------------------
-    * Pre  :
-    * Post : Returns GL text output agent
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.04:
-    * Mongoose - Created
-    ------------------------------------------------------*/
-
-    //! \fixme Should be private
-   void drawLoadScreen();
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-    * Post : Renders load screen
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
-    void addSkeletalModel(SkeletalModel *mdl);
-   /*------------------------------------------------------
-    * Pre  :
-    * Post :
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
+    /*!
+     * \brief Get the GL text output agent
+     * \returns Used GLString instance
+     */
+    GLString *GetString();
 
+    /*!
+     * \brief Renders load screen.
+     *
+     * Textures must be initialized.
+     * \fixme Should be private!
+     */
+    void drawLoadScreen();
 
-private:
+    void addSkeletalModel(SkeletalModel *mdl);
 
-    ////////////////////////////////////////////////////////////
-    // Private Accessors
-    ////////////////////////////////////////////////////////////
+private:
 
+    /*!
+     * \brief Check if a bounding box is in the View Volume
+     * \param bboxMin Start coordinates of a valid bounding box
+     * \param bboxMax End coordinates of a valid bounding box
+     * \returns true if bounding box is visible
+     */
     bool isVisible(float bboxMin[3], float bboxMax[3]);
-    /*------------------------------------------------------
-     * Pre  : Abstract bounding box must be valid
-     * Post : If object's bounding box is in viewing volume
-     *        return true, else false
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.16:
-     * Mongoose - Moved to Render class
-     *
-     * 2001.06.06:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Check if a point is in the View Volume
+     * \param x X coordinate
+     * \param y Y coordinate
+     * \param z Z coordinate
+     * \returns true if point is visible
+     */
     bool isVisible(float x, float y, float z);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Is point in view volume?
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.16:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Check if a sphere is in the View Volume
+     * \param x X coordinate of center of sphere
+     * \param y Y coordinate of center of sphere
+     * \param z Z coordinate of center of sphere
+     * \param radius radius of sphere
+     * \returns true if sphere is visible
+     */
     bool isVisible(float x, float y, float z, float radius);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Is sphere in view volume?
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.16:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Private Mutators
-    ////////////////////////////////////////////////////////////
 
+    /*!
+     * \brief Build a visible room list starting at index
+     * \param index valid room index where to start the list
+     */
     void newRoomRenderList(int index);
-   /*------------------------------------------------------
-    * Pre  : room index is valid
-    * Post : Build a visible room list starting at index
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Build a visible room list starting from room and
+     * only considers its linked rooms and their linked rooms.
+     * \param room First room in list
+     */
     void buildRoomRenderList(RenderRoom *room);
-   /*------------------------------------------------------
-    * Pre  : room is valid
-    * Post : Build a visible room list starting from room
-     *        and only consider it's linked rooms and their
-     *        linked rooms
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders visible world object.
+     *
+     * Texture must be initialized.
+     */
     void drawObjects();
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-    * Post : Renders visible world objects
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders Sky domes/boxes/etc by scaling factor.
+     *
+     * Texture must be initialized.
+     * \param scale correct scale for map size
+     */
     void drawSkyMesh(float scale);
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-     *        scale is correct for map size
-    * Post : Renders Sky domes/boxes/etc by scaling factor
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders a skeletal model.
+     *
+     * Texture must be initialized!
+     * \param model model to render
+     */
     void drawModel(SkeletalModel *model);
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-    * Post : Renders a skeletal model
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
-    void drawRoom(RenderRoom *rRoom, bool draw_alpha);
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-     *        Draw all rooms with alpha false, then
-     *        draw with alpha true
+    /*!
+     * Renders a room in 2 seperate passes to handle alpha.
      *
-    * Post : Renders a room in 2 seperate passes to
-     *        handle alpha, currently doesn't sort alpha
-     *        but looks pretty good
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
+     * Currently doesnt sort alpha but looks pretty good.
+     * Texture must be initialized.
+     * Draw all rooms with alpha false, then again with alpha true.
+     * \param rRoom room to render
+     * \param draw_alpha once false, once true
+     */
+    void drawRoom(RenderRoom *rRoom, bool draw_alpha);
 
+    /*!
+     * \brief Renders static room model.
+     *
+     * Texture must be initialized.
+     * \param mesh Static model to render
+     */
     void drawRoomModel(static_model_t *mesh);
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-    * Post : Renders static room model
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders a mesh.
+     *
+     * Texture must be initialized.
+     * \param r_mesh Mesh to render.
+     * \param type Must be object containing mesh
+     */
     void drawModelMesh(model_mesh_t *r_mesh, RenderMeshType type);
-   /*------------------------------------------------------
-    * Pre  : Texture is init, type is object containing mesh
-    * Post : Renders a mesh
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Renders a sprite.
+     *
+     * Texture must be initialized.
+     * \param sprite sprite to render
+     */
     void drawSprite(sprite_t *sprite);
-   /*------------------------------------------------------
-    * Pre  : Texture is init
-    * Post : Renders a sprite
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.01:
-    * Mongoose - Created
-    ------------------------------------------------------*/
 
+    /*!
+     * \brief Updates View Volume. Call once per render frame.
+     */
     void updateViewVolume();
-    /*------------------------------------------------------
-     * Pre  : Call once per render frame
-     * Post : Updated view volume
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.12.16:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    //! \fixme Let them eat cake...? O.o
     void tmpRenderModelMesh(model_mesh_t *r_mesh, texture_tri_t *ttri);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Let them eat cake...
-     *
-     *-- History ------------------------------------------
-     *
-     * 2003.05.19:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-
-#ifdef USING_EMITTER
-    Emitter *mEmitter;      /* Particle emitter test */
-#endif
-
-    Texture mTexture;       /* Texture subsystem */
-
-    Camera *mCamera;        /* Camera subsystem */
-
-    GLString mString;       /* GL Text subsystem */
 
+    Texture mTexture;                     //!< Texture subsystem
+    Camera *mCamera;                      //!< Camera subsystem
+    GLString mString;                     //!< GL Text subsystem
     Vector<RenderRoom *> mRoomRenderList;
-
     Vector<RenderRoom *> mRooms;
-
     Vector<SkeletalModel *> mModels;
-
-    unsigned int mFlags;    /* Rendering flags */
-
-    unsigned int mWidth;    /* Viewport width */
-
-    unsigned int mHeight;   /* Viewport height */
-
-    unsigned int mMode;     /* Rendering mode */
-
+    unsigned int mFlags;                  //!< Rendering flags
+    unsigned int mWidth;                  //!< Viewport width
+    unsigned int mHeight;                 //!< Viewport height
+    unsigned int mMode;                   //!< Rendering mode
     unsigned int *mNumTexturesLoaded;
-
     unsigned int *mNextTextureId;
-
-    // float mSplash;
-
     int mLock;
-
-    int mSkyMesh;           /* Skymesh model id */
-
-    bool mSkyMeshRotation;  /* Should Skymesh be rotated? */
+    int mSkyMesh;                         //!< Skymesh model id
+    bool mSkyMeshRotation;                //!< Should Skymesh be rotated?
+#ifdef USING_EMITTER
+    Emitter *mEmitter;                    //!< Particle emitter test
+#endif
 };
 
 #endif

src/Render.cpp

@@ -1,23 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file src/Render.cpp
+ * \brief OpenRaider Renderer class
  *
- * Project : Render
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Render
- * License : No use w/o permission (C) 2001 Mongoose
- * Comments: This is the renderer class for OpenRaider
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History -------------------------------------------------
- *
- * 2001.05.21:
- * Mongoose - Created
- =================================================================*/
+ * \author Mongoose
+ */
 
 #ifdef __APPLE__
 #include <OpenGL/gl.h>
@@ -579,15 +565,6 @@ void lightRoom(RenderRoom *room)
 }
 
 
-void Render::toggleFlag(unsigned int flag)
-{
-    if (mFlags & flag)
-        clearFlags(flag);
-    else
-        setFlags(flag);
-}
-
-
 void Render::clearFlags(unsigned int flags)
 {
     // _defaults |= flags; // Force removal if it wasn't set