Improved documentation

src/OpenGLMesh.cpp

@@ -1,23 +1,11 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file OpenGLMesh.cpp
+ * \brief OpenGL Mesh
  *
- * Project : OpenRaider
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : OpenGLMesh
- * License : No use w/o permission (C) 2002 Mongoose
- * Comments:
+ * Defining UNIT_TEST_OPENGLMESH builds OpenGLMesh class as a console unit test
  *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History -------------------------------------------------
- *
- * 2002.08.23:
- * Mongoose - Created
- =================================================================*/
+ * \author Mongoose
+ */
 
 #ifdef __APPLE__
 #include <OpenGL/gl.h>

src/OpenGLMesh.h

@@ -1,420 +1,218 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file OpenGLMesh.h
+ * \brief OpenGL Mesh
  *
- * Project : OpenRaider
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : OpenGLMesh
- * License : No use w/o permission (C) 2002 Mongoose
- * Comments:
+ * Defining UNIT_TEST_OPENGLMESH builds OpenGLMesh class as a console unit test
  *
+ * \author Mongoose
  *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- Test Defines -----------------------------------------------
- *
- * UNIT_TEST_OPENGLMESH - Builds OpenGLMesh class as a console unit test
- *
- *-- History ------------------------------------------------
- *
- * 2002.08.23:
- * Mongoose - Created
- ================================================================*/
-
+ * \todo Unify the parallel systems here, arrays and the allocate/set
+ */
 
 #ifndef GUARD__OPENRAIDER_MONGOOSE_OPENGLMESH_H_
 #define GUARD__OPENRAIDER_MONGOOSE_OPENGLMESH_H_
 
 #include "hel/math.h"
 
-// TODO: Unify the parallel systems here, arrays and the allocate/set
+class OpenGLMesh {
+public:
 
+    typedef enum {
+        OpenGLMeshModeSolid          = 0,
+        OpenGLMeshModeWireframe      = 1,
+        OpenGLMeshModeTexture        = 2,
+        OpenGLMeshModeMultiTexture   = 3
+    } OpenGLMeshMode;
 
-typedef enum
-{
-	OpenGLMeshModeSolid          = 0,
-	OpenGLMeshModeWireframe      = 1,
-	OpenGLMeshModeTexture        = 2,
-	OpenGLMeshModeMultiTexture   = 3
+    typedef enum {
+        fOpenGLMesh_Transparent      = 1,
+        fOpenGLMesh_BumpMap          = 2,
+        fOpenGLMesh_UseVertexArray   = 4
+    } OpenGLMeshFlags;
 
-} OpenGLMeshMode;
+    typedef struct tris_s {
+        int texture;
+#ifdef MULTITEXTURE
+        int bumpmap;
+#endif
 
-enum OpenGLMeshFlags
-{
-	fOpenGLMesh_Transparent      = 1,
-	fOpenGLMesh_BumpMap          = 2,
-	fOpenGLMesh_UseVertexArray   = 4
-};
+        unsigned int cnum_triangles;
+        unsigned int cnum_alpha_triangles;
 
+        unsigned int num_texcoors;
+        vec2_t *texcoors;
 
-typedef struct tris_s
-{
-	int texture;
+        unsigned int num_texcoors2;
+        vec2_t *texcoors2;
+
+        //! Arrays of triangle indices sorted by texture
+        unsigned int num_triangles;
+        unsigned int *triangles; //!< ABCABCABC...
+
+        //! Arrays of alpha triangle indices sorted by texture
+        unsigned int num_alpha_triangles;
+        unsigned int *alpha_triangles; //!< ABCABCABC...
+    } tris_t;
+
+    typedef struct rect_s {
+
+        int texture;
 #ifdef MULTITEXTURE
-	int bumpmap;
+        int bumpmap;
 #endif
 
-	unsigned int cnum_triangles;
-	unsigned int cnum_alpha_triangles;
+        unsigned int cnum_quads;
+        unsigned int cnum_alpha_quads;
 
-	unsigned int num_texcoors;
-	vec2_t *texcoors;
+        unsigned int num_texcoors;
+        vec2_t *texcoors;
 
-	unsigned int num_texcoors2;
-	vec2_t *texcoors2;
+        unsigned int num_texcoors2;
+        vec2_t *texcoors2;
 
-	// Arrays of triangle indices sorted by texture
-	unsigned int num_triangles;
-	unsigned int *triangles; // ABCABCABC...
+        //! Arrays of rectangle indices sorted by texture
+        unsigned int num_quads;
+        unsigned int *quads; //!< ABCDABCDABCD...
 
-	// Arrays of alpha triangle indices sorted by texture
-	unsigned int num_alpha_triangles;
-	unsigned int *alpha_triangles; // ABCABCABC...
+        //! Arrays of alpha rectangle indices sorted by texture
+        unsigned int num_alpha_quads;
+        unsigned int *alpha_quads; //!< ABCDABCDABCD...
 
-} tris_t;
+    } rect_t;
 
+    ////////////////////////////////////////////////////////////
+    // Constructors
+    ////////////////////////////////////////////////////////////
 
-typedef struct rect_s
-{
-	int texture;
-#ifdef MULTITEXTURE
-	int bumpmap;
-#endif
+    /*!
+     * \brief Constructs an object of OpenGLMesh
+     */
+    OpenGLMesh();
+
+    /*!
+     * \brief Deconstructs an object of OpenGLMesh
+     */
+    ~OpenGLMesh();
+
+
+    ////////////////////////////////////////////////////////////
+    // Public Accessors
+    ////////////////////////////////////////////////////////////
+
+
+    void drawAlpha();
+
+
+    void drawSolid();
+
+
+    ////////////////////////////////////////////////////////////
+    // Public Mutators
+    ////////////////////////////////////////////////////////////
+
+
+    void allocateColors(unsigned int n);
+
+
+    void allocateNormals(unsigned int n);
+
+
+    void allocateRectangles(unsigned int n);
 
-	unsigned int cnum_quads;
-	unsigned int cnum_alpha_quads;
-
-	unsigned int num_texcoors;
-	vec2_t *texcoors;
-
-	unsigned int num_texcoors2;
-	vec2_t *texcoors2;
-
-	// Arrays of rectangle indices sorted by texture
-	unsigned int num_quads;
-	unsigned int *quads; // ABCDABCDABCD...
-
-	// Arrays of alpha rectangle indices sorted by texture
-	unsigned int num_alpha_quads;
-	unsigned int *alpha_quads; // ABCDABCDABCD...
-
-} rect_t;
-
-
-class OpenGLMesh
-{
- public:
-
-	////////////////////////////////////////////////////////////
-	// Constructors
-	////////////////////////////////////////////////////////////
-
-	OpenGLMesh();
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post : Constructs an object of OpenGLMesh
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	~OpenGLMesh();
-	/*------------------------------------------------------
-	 * Pre  : OpenGLMesh object is allocated
-	 * Post : Deconstructs an object of OpenGLMesh
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-
-	////////////////////////////////////////////////////////////
-	// Public Accessors
-	////////////////////////////////////////////////////////////
-
-	void drawAlpha();
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post : Render alpha polygons
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void drawSolid();
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post : Render solid polygons
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-
-	////////////////////////////////////////////////////////////
-	// Public Mutators
-	////////////////////////////////////////////////////////////
-
-	void allocateColors(unsigned int n);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void allocateNormals(unsigned int n);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void allocateRectangles(unsigned int n);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void allocateTriangles(unsigned int n);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void allocateVertices(unsigned int n);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void bufferColorArray(unsigned int colorCount, vec_t *colors,
-								 unsigned int colorWidth);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.20:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void bufferNormalArray(unsigned int normalCount, vec_t *normals);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.20:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void bufferTriangles(unsigned int count,
-								unsigned int *indices, vec_t *texCoords,
-								int *textures, unsigned int *flags);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void bufferVertexArray(unsigned int vertexCount, vec_t *vertices);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.20:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void setColor(unsigned int index, float r, float g, float b, float a);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void setColor(unsigned int index, float rgba[4]);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void setNormal(unsigned int index, float i, float j, float k);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void setVertex(unsigned int index, float x, float y, float z);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2002.08.23:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
+
+    void allocateTriangles(unsigned int n);
+
+
+    void allocateVertices(unsigned int n);
+
+
+    void bufferColorArray(unsigned int colorCount, vec_t *colors,
+                                 unsigned int colorWidth);
+
+
+    void bufferNormalArray(unsigned int normalCount, vec_t *normals);
+
+
+    void bufferTriangles(unsigned int count,
+                                unsigned int *indices, vec_t *texCoords,
+                                int *textures, unsigned int *flags);
+
+    void bufferVertexArray(unsigned int vertexCount, vec_t *vertices);
+
+
+    void setColor(unsigned int index, float r, float g, float b, float a);
+
+
+    void setColor(unsigned int index, float rgba[4]);
+
+
+    void setNormal(unsigned int index, float i, float j, float k);
+
+
+    void setVertex(unsigned int index, float x, float y, float z);
 
 #ifdef NOT_IMPLEMENTED
-	void sortFacesByTexture();
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void addFace(int textureIndex, int textureIndexB, unsigned int flags,
-					 unsigned int vertexIndexCount, vec_t *vertexIndices);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void addTexTiledFace(int textureIndex, int textureIndexB,
-								unsigned int flags, unsigned int indexCount,
-								vec_t *vertexIndices, vec_t *texcoords);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void bufferTexcoords(unsigned int texcoordCount, vec_t *texcoords);
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-
-	void duplicateArraysForTexTiledTexcoords();
-	/*------------------------------------------------------
-	 * Pre  :
-	 * Post :
-	 *
-	 *-- History ------------------------------------------
-	 *
-	 * 2003.05.26:
-	 * Mongoose - Created
-	 ------------------------------------------------------*/
-#endif
 
 
-	unsigned int mFlags;
+    void sortFacesByTexture();
+
+
+    void addFace(int textureIndex, int textureIndexB, unsigned int flags,
+                     unsigned int vertexIndexCount, vec_t *vertexIndices);
 
-	OpenGLMeshMode mMode;
 
-	unsigned int mNumVertices;
-	vec3_t *mVertices;  // <XYZ>
+    void addTexTiledFace(int textureIndex, int textureIndexB,
+                                unsigned int flags, unsigned int indexCount,
+                                vec_t *vertexIndices, vec_t *texcoords);
+
+
+    void bufferTexcoords(unsigned int texcoordCount, vec_t *texcoords);
+
+
+    void duplicateArraysForTexTiledTexcoords();
+
+#endif
+
+    unsigned int mFlags;
 
-	unsigned int mNumNormals;
-	vec3_t *mNormals;   // <IJK>
+    OpenGLMeshMode mMode;
 
-	unsigned int mNumColors;
-	vec4_t *mColors;    // <RGBA>
+    unsigned int mNumVertices;
+    vec3_t *mVertices; //!< XYZ
 
-	unsigned int mNumTris;
-	tris_t *mTris;
+    unsigned int mNumNormals;
+    vec3_t *mNormals; //!< IJK
 
-	unsigned int mNumQuads;
-	rect_t *mQuads;
+    unsigned int mNumColors;
+    vec4_t *mColors; //!< RGBA
 
+    unsigned int mNumTris;
+    tris_t *mTris;
 
-	unsigned int mTriangleCount;
-	int *mTriangleTextures;
-	unsigned int *mTriangleIndices;
-	unsigned int *mTriangleFlags;
-	vec_t *mTriangleTexCoordArray;
+    unsigned int mNumQuads;
+    rect_t *mQuads;
 
-	vec_t *mVertexArray;
-	vec_t *mNormalArray;
-	vec_t *mColorArray;
+    unsigned int mTriangleCount;
+    int *mTriangleTextures;
+    unsigned int *mTriangleIndices;
+    unsigned int *mTriangleFlags;
+    vec_t *mTriangleTexCoordArray;
 
- private:
+    vec_t *mVertexArray;
+    vec_t *mNormalArray;
+    vec_t *mColorArray;
 
-	////////////////////////////////////////////////////////////
-	// Private Accessors
-	////////////////////////////////////////////////////////////
+private:
 
+    ////////////////////////////////////////////////////////////
+    // Private Accessors
+    ////////////////////////////////////////////////////////////
 
-	////////////////////////////////////////////////////////////
-	// Private Mutators
-	////////////////////////////////////////////////////////////
 
+    ////////////////////////////////////////////////////////////
+    // Private Mutators
+    ////////////////////////////////////////////////////////////
 
-	/* */
 };
 
 #endif

src/OpenRaider.cpp

@@ -123,8 +123,9 @@ OpenRaider::OpenRaider() : SDLSystem()
 	m_testSFX = -1;
 	mNoClipping = 0;
 
-	// TODO, Replace numbers with enum modes
-	// Only do this when you know the amount of commands + 1 ( 0 reserved )
+	/*! \todo Replace numbers with enum modes.
+	 * Only do this when you know the amount of commands + 1 (0 reserved)
+     */
 	mMode[addCommandMode("[OpenRaider.Engine]")] = 2;
 	mMode[addCommandMode("[Network.Server]")] = 5;
 	mMode[addCommandMode("[Video.OpenGL]")] = 0;

src/Render.cpp

@@ -1808,13 +1808,13 @@ void Render::drawRoom(RenderRoom *rRoom, bool draw_alpha)
 	switch (mMode)
 	{
 	case modeWireframe:
-		rRoom->mesh.mMode = OpenGLMeshModeWireframe;
+		rRoom->mesh.mMode = OpenGLMesh::OpenGLMeshModeWireframe;
 		break;
 	case modeSolid:
-		rRoom->mesh.mMode = OpenGLMeshModeSolid;
+		rRoom->mesh.mMode = OpenGLMesh::OpenGLMeshModeSolid;
 		break;
 	default:
-		rRoom->mesh.mMode = OpenGLMeshModeTexture;
+		rRoom->mesh.mMode = OpenGLMesh::OpenGLMeshModeTexture;
 		break;
 	}
 

src/SDLSystem.cpp

@@ -619,7 +619,7 @@ void SDLSystem::toggleFullscreen()
                 mFullscreen = !mFullscreen;
             }
             if (dimensions != (SDL_Rect **)-1) {
-                // TODO dont just use first available resolution...
+                //! \fixme Don't just use first available resolution...
                 width = dimensions[0]->w;
                 height = dimensions[0]->h;
             } else {

src/SkeletalModel.h

@@ -1,32 +1,15 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file SkeletalModel.h
+ * \brief This is the factored out skeletal model class
  *
- * Project : OpenRaider
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : SkeletalModel
- * License : No use w/o permission (C) 2003 Mongoose
- * Comments: This is the factored out skeletal model class
+ * Defining UNIT_TEST_SKELETALMODEL builds SkeletalModel class as a console unit test
  *
+ * \author Mongoose
  *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- Test Defines -----------------------------------------------
- *
- * UNIT_TEST_SKELETALMODEL - Builds SkeletalModel class as a console unit test
- *
- *-- History ------------------------------------------------
- *
- * 2003.05.19:
- * Mongoose - Created
- ================================================================*/
-
-// TODO
-// Start cutting off old hacks by simple force use of method interface
-// Also move the publicly exposed attributes out  =)
-// Better animation system in general - this is memory wasteful
+ * \todo Start cutting off old hacks by simple force use of method interface.
+ * Also move the publicly exposed attributes out  =)
+ * Better animation system in general - this is memory wasteful
+ */
 
 #ifndef GUARD__OPENRAIDER_MONGOOSE_SKELETALMODEL_H_
 #define GUARD__OPENRAIDER_MONGOOSE_SKELETALMODEL_H_