Documented Emitter

include/Emitter.h

@@ -1,292 +1,179 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file include/Emitter.h
+ * \brief Particle emitter class.
  *
- * Project : Freyja
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Emitter
- * License : No use w/o permission (C)2001Mongoose
- * Comments: Particle emitter for freyja
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2001.08.13:
- * Mongoose - Now using new Particle class!
- *
- * 2001.06.30:
- * Mongoose - Created
- ================================================================*/
-
+ * \author Mongoose
+ */
 
 #ifndef _EMITTER_H_
 #define _EMITTER_H_
 
 #include <Particle.h>
 
-
-class Emitter
-{
- public:
-
-    typedef enum
-    {
-        fUseFrustumCulling = 1,
-        fUseDepthSorting = 2
+/*!
+ * \brief Particle emitter class.
+ */
+class Emitter {
+public:
+
+    /*!
+     * \brief Flags an Emitter can have
+     */
+    typedef enum {
+        fUseFrustumCulling = (1 << 0), //!< Use frustum culling
+        fUseDepthSorting   = (1 << 1)  //!< Use depth sorting
     } EmitterFlags;
 
 
-  Emitter(const char *name, int n);
-  /*------------------------------------------------------
-   * Pre  : name is a valid C string
-    *        n is a number greater than 0
-    *
-   * Post : Constructs an object of Emitter
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.06.30:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  ~Emitter();
-  /*------------------------------------------------------
-   * Pre  : Emitter object is allocated
-   * Post : Deconstructs an object of Emitter
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.06.30:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-   Particle *Particles();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Returns particle array
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  int Count();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Returns number of particles emitted
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Pos(float x, float y, float z);
-  /*------------------------------------------------------
-   * Pre  : x,y,z exist
-   * Post : Sets position of emitter in 3 space
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Pos(float *x, float *y, float *z);
-  /*------------------------------------------------------
-   * Pre  : x,y,z exist
-   * Post : Returns position of emitter in 3 space
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
+    /*!
+     * \brief Constructs an object of Emitter
+     * \param name valid C string
+     * \param n greater than 0
+     */
+    Emitter(const char *name, int n);
+
+    /*!
+     * \brief Deconstructs an object of Emitter
+     */
+    ~Emitter();
+
+    /*!
+     * \brief Get the particles
+     * \returns array of Particles
+     */
+    Particle *Particles();
+
+    /*!
+     * \brief Number of particles emitted
+     * \returns Number of particles emitted
+     */
+    int Count();
+
+    /*!
+     * \brief Sets position of emitter in 3D space
+     * \param x X coordinate
+     * \param y Y coordinate
+     * \param z Z coordinate
+     */
+    void Pos(float x, float y, float z);
+
+    /*!
+     * \brief Returns position of emitter in 3D space
+     * \param x Where X coordinate will be stored
+     * \param y Where Y coordinate will be stored
+     * \param z Where Z coordinate will be stored
+     */
+    void Pos(float *x, float *y, float *z);
+
+    /*!
+     * \brief Sets orientation of emitter in 3D space
+     * \param x X coordinate
+     * \param y Y coordinate
+     * \param z Z coordinate
+     */
     void Orientation(float x, float y, float z);
-  /*------------------------------------------------------
-   * Pre  : x,y,z exist
-   * Post : Sets orientation of emitter in 3 space
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 
+    /*!
+     * \brief Returns orientation of emitter in 3D space
+     * \param x Where X coordinate will be stored
+     * \param y Where Y coordinate will be stored
+     * \param z Where Z coordinate will be stored
+     */
     void Orientation(float *x, float *y, float *z);
-  /*------------------------------------------------------
-   * Pre  : x,y,z exist
-   * Post : Returns orientation of emitter in 3 space
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  unsigned int Flags();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Returns emitter flags
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-
-  void Flags(unsigned int flag, bool op);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Set and Unset flag with op
-    *
-    *          true - set
-    *          flase - unset
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void ParticleArray(int n);
-  /*------------------------------------------------------
-   * Pre  : n is a number greater than 0
-   * Post : Allocates the particle array and sets the count.
-    *        If the array has been allocated previously, then
-    *        the array is deallocated and a new one made.
-    *
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Draw();
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Renders particles
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.06.30:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Name(const char *name);
-  /*------------------------------------------------------
-   * Pre  : name is a valid C string
-   * Post : Sets the emitters name
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void SetTextureId(int id);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Resets all particle texture ids
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.13:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void TextureId(unsigned int particle_start, unsigned int particle_end,
-                      int id);
-  /*------------------------------------------------------
-   * Pre  : particle_start and particle_end are a valid
-    *        range of particles in the array
-    *
-    *        id is a valid texture id
-    *
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Color(unsigned int particle_start, unsigned int particle_end,
-                 float r, float g, float b);
-  /*------------------------------------------------------
-   * Pre  : particle_start and particle_end are a valid
-    *        range of particles in the array
-    *
-    *        r,g,b are colors 0.0 to 1.0
-    *
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Speed(unsigned int particle_start, unsigned int particle_end,
-                 float x, float y, float z);
-  /*------------------------------------------------------
-   * Pre  : particle_start and particle_end are a valid
-    *        range of particles in the array
-    *
-    *        take note speed inits at 2000, lower is faster
-    *
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  void Force(unsigned int particle_start, unsigned int particle_end,
-                 float x, float y, float z);
-  /*------------------------------------------------------
-   * Pre  : particle_start and particle_end are a valid
-    *        range of particles in the array
-    *
-    *        Force/Gravity acting on particles
-    *
-   * Post :
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.08.14:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-
-    static vec_t mFrustum[6][4]; /* View Volume copy */
-
-
- private:
 
+    /*!
+     * \brief Get the flags of this Emitter
+     * \returns EmitterFlags
+     */
+    unsigned int Flags();
+
+    /*!
+     * \brief Set or Unset a flag
+     * \param flag EmitterFlag to change
+     * \param op new state (true - set)
+     */
+    void Flags(unsigned int flag, bool op);
+
+    /*!
+     * \brief Allocates the particle array and sets the count.
+     * If the array has been allocated previously it will be
+     * deallocated and a new one made.
+     * \param n new size, greater than 0
+     */
+    void ParticleArray(int n);
+
+    /*!
+     * \brief Renders the particles
+     */
+    void Draw();
+
+    /*!
+     * \brief Sets the emitters name
+     * \param name is a valid C string
+     */
+    void Name(const char *name);
+
+    /*!
+     * \brief Resets all particle texture ids
+     * \param id new id
+     * \sa Particle::TextureId()
+     */
+    void SetTextureId(int id);
+
+    /*!
+     * \brief Set the texture id for a range of particles in the array
+     * \param particle_start start of range
+     * \param particle_end end of range
+     * \param id new id
+     * \sa Particle::TextureId()
+     */
+    void TextureId(unsigned int particle_start, unsigned int particle_end, int id);
+
+    /*!
+     * \brief Set the color of a range of particles in the array
+     * \param particle_start start of range
+     * \param particle_end end of range
+     * \param r new red part of color (0.0 to 1.0)
+     * \param g new green part of color (0.0 to 1.0)
+     * \param b new blue part of color (0.0 to 1.0)
+     * \sa Particle::Color()
+     */
+    void Color(unsigned int particle_start, unsigned int particle_end, float r, float g, float b);
+
+    /*!
+     * \brief Set the speed of a range of particles in the array.
+     * Take note that the speed starts out at 2000, and lower means faster.
+     * \param particle_start start of range
+     * \param particle_end end of range
+     * \param x X speed
+     * \param y Y speed
+     * \param z Z speed
+     * \sa Particle::Speed
+     */
+    void Speed(unsigned int particle_start, unsigned int particle_end, float x, float y, float z);
+
+    /*!
+     * \brief Let a force (eg. Gravity) act on a range of particles in the array
+     * \param particle_start start of range
+     * \param particle_end end of range
+     * \param x X force
+     * \param y Y force
+     * \param z Z force
+     * \sa Particle::Force()
+     */
+    void Force(unsigned int particle_start, unsigned int particle_end, float x, float y, float z);
+
+    static vec_t mFrustum[6][4]; //!< View Volume copy
+
+private:
     static int compareParticleDist(const void *voidA, const void *voidB);
 
-
-    char *_name;              /* Emitter name */
-
-    unsigned int _flags;      /* Emitter flags */
-
-    vec3_t _pos;              /* Position in 3 space */
-
-    vec3_t _mangle;           /* Oreintation in 3 space */
-
-    Particle *_particle;      /* Array of particles */
-
-    unsigned int _count;      /* Particle count */
+    char *_name;         //!< Emitter name
+    unsigned int _flags; //!< Emitter flags
+    vec3_t _pos;         //!< Position in 3D space
+    vec3_t _mangle;      //!< Oreintation in 3D space
+    Particle *_particle; //!< Array of particles
+    unsigned int _count; //!< Particle count
 };
 
 #endif

src/Emitter.cpp

@@ -1,23 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file src/Emitter.cpp
+ * \brief Particle emitter class.
  *
- * Project : Freyja
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Emitter
- * License : No use w/o permission (C)2001Mongoose
- * Comments: Particle emitter for freyja
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History -------------------------------------------------
- *
- * 2001.06.30:
- * Mongoose - Created
- =================================================================*/
+ * \author Mongoose
+ */
 
 #include <stdlib.h>
 #include <string.h>
@@ -38,9 +24,7 @@
 
 vec_t Emitter::mFrustum[6][4];
 
-
-int Emitter::compareParticleDist(const void *voidA, const void *voidB)
-{
+int Emitter::compareParticleDist(const void *voidA, const void *voidB) {
     Particle *a = (Particle *)voidA, *b = (Particle *)voidB;
     float x, y, z, distA, distB;
 
@@ -68,9 +52,7 @@ int Emitter::compareParticleDist(const void *voidA, const void *voidB)
     return 1;
 }
 
-
-Emitter::Emitter(const char *name, int n)
-{
+Emitter::Emitter(const char *name, int n) {
     _name = NULL;
     _flags = 0;
     _particle = NULL;
@@ -82,87 +64,63 @@ Emitter::Emitter(const char *name, int n)
     ParticleArray(n);
 }
 
-
-Emitter::~Emitter()
-{
+Emitter::~Emitter() {
     if (_name)
-    {
         delete [] _name;
-    }
 
     if (_particle)
-    {
         delete [] _particle;
-    }
 
     _count = 0;
 }
 
-Particle *Emitter::Particles()
-{
+Particle *Emitter::Particles() {
     return _particle;
 }
 
 
-int Emitter::Count()
-{
+int Emitter::Count() {
     return _count;
 }
 
-
-void Emitter::Pos(float *x, float *y, float *z)
-{
+void Emitter::Pos(float *x, float *y, float *z) {
     *x = _pos[0];
     *y = _pos[1];
     *z = _pos[2];
 }
 
-
-void Emitter::Pos(float x, float y, float z)
-{
+void Emitter::Pos(float x, float y, float z) {
     _pos[0] = x;
     _pos[1] = y;
     _pos[2] = z;
 }
 
-
-void Emitter::Orientation(float *x, float *y, float *z)
-{
+void Emitter::Orientation(float *x, float *y, float *z) {
     *x = _mangle[0];
     *y = _mangle[1];
     *z = _mangle[2];
 }
 
-
-void Emitter::Orientation(float x, float y, float z)
-{
+void Emitter::Orientation(float x, float y, float z) {
     _mangle[0] = x;
     _mangle[1] = y;
     _mangle[2] = z;
 }
 
-
-unsigned int Emitter::Flags()
-{
+unsigned int Emitter::Flags() {
     return _flags;
 }
 
-
-void Emitter::Flags(unsigned int flag, bool op)
-{
+void Emitter::Flags(unsigned int flag, bool op) {
     _flags |= flag;
 
     if (!op)
         _flags ^= flag;
 }
 
-
-void Emitter::ParticleArray(int n)
-{
-    if (n)
-    {
-        if (_particle)
-        {
+void Emitter::ParticleArray(int n) {
+    if (n) {
+        if (_particle) {
             _count = 0;
             delete [] _particle;
         }
@@ -172,20 +130,12 @@ void Emitter::ParticleArray(int n)
     }
 }
 
-
-void Emitter::Name(const char *name)
-{
-    int l;
-
-
-    if (name && name[0])
-    {
+void Emitter::Name(const char *name) {
+    if (name && name[0]) {
         if (_name)
-        {
             delete [] _name;
-        }
 
-        l = strlen(name);
+        int l = strlen(name);
         _name = new char[l+1];
 
         // Mongoose 2002.01.09, Mongoose says 'Only you can prevent overflows'
@@ -194,91 +144,46 @@ void Emitter::Name(const char *name)
     }
 }
 
-
-void Emitter::SetTextureId(int id)
-{
-    unsigned int i;
-
-
-    for (i = 0; i < _count; i++)
+void Emitter::SetTextureId(int id) {
+    for (unsigned int i = 0; i < _count; i++)
         _particle[i].TextureId(id);
 }
 
-
-void Emitter::TextureId(unsigned int particle_start,
-        unsigned int particle_end, int id)
-{
-    unsigned int i;
-
-
-    if ((particle_start < _count) &&
-            (particle_end > 0 && particle_end <= _count) &&
-            (particle_start < particle_end))
-    {
-        for (i = particle_start; i < particle_end; i++)
+void Emitter::TextureId(unsigned int particle_start, unsigned int particle_end, int id) {
+    if ((particle_start < _count) && (particle_end > 0 && particle_end <= _count) && (particle_start < particle_end)) {
+        for (unsigned int i = particle_start; i < particle_end; i++)
             _particle[i].TextureId(id);
     }
 }
 
-
-void Emitter::Color(unsigned int particle_start, unsigned int particle_end,
-        float r, float g, float b)
-{
-    unsigned int i;
-
-
-    if ((particle_start < _count) &&
-            (particle_end > 0 && particle_end <= _count) &&
-            (particle_start < particle_end))
-    {
-        for (i = particle_start; i < particle_end; i++)
+void Emitter::Color(unsigned int particle_start, unsigned int particle_end, float r, float g, float b) {
+    if ((particle_start < _count) && (particle_end > 0 && particle_end <= _count) && (particle_start < particle_end)) {
+        for (unsigned int i = particle_start; i < particle_end; i++)
             _particle[i].Color(r, g, b);
     }
 }
 
-
-void Emitter::Speed(unsigned int particle_start, unsigned int particle_end,
-        float x, float y, float z)
-{
-    unsigned int i;
-
-
-    if ((particle_start < _count) &&
-            (particle_end > 0 && particle_end <= _count) &&
-            (particle_start < particle_end))
-    {
-        for (i = particle_start; i < particle_end; i++)
+void Emitter::Speed(unsigned int particle_start, unsigned int particle_end, float x, float y, float z) {
+    if ((particle_start < _count) && (particle_end > 0 && particle_end <= _count) && (particle_start < particle_end)) {
+        for (unsigned int i = particle_start; i < particle_end; i++)
             _particle[i].Speed(x, y, z);
     }
 }
 
-
-void Emitter::Force(unsigned int particle_start, unsigned int particle_end,
-        float x, float y, float z)
-{
-    unsigned int i;
-
-
-    if ((particle_start < _count) &&
-            (particle_end > 0 && particle_end <= _count) &&
-            (particle_start < particle_end))
-    {
-        for (i = particle_start; i < particle_end; i++)
+void Emitter::Force(unsigned int particle_start, unsigned int particle_end, float x, float y, float z) {
+    if ((particle_start < _count) && (particle_end > 0 && particle_end <= _count) && (particle_start < particle_end)) {
+        for (unsigned int i = particle_start; i < particle_end; i++)
             _particle[i].Force(x, y, z);
     }
 }
 
-
-void Emitter::Draw()
-{
+void Emitter::Draw() {
     unsigned int i, p;
     float x, y, z;
     float r, g, b;
     float life;
 
-
-    if (!_count || !_particle)
-    {
+    if (!_count || !_particle) {
         printf("Emitter::Draw> No particles!\n");
         return;
     }
@@ -291,25 +196,15 @@ void Emitter::Draw()
     //glTranslatef(_pos[0], _pos[1], _pos[2]);
 
     if (_flags & fUseDepthSorting)
-    {
         qsort(_particle, _count, sizeof(Particle), compareParticleDist);
-    }
 
-    for (i = 0; i < _count; i++)
-    {
-        if (_particle[i].isActive())
-        {
+    for (i = 0; i < _count; i++) {
+        if (_particle[i].isActive()) {
             _particle[i].Pos(&x, &y, &z);
 
-            if (_flags & fUseFrustumCulling)
-            {
-                for (p = 0; p < 6; ++p)
-                {
-                    if (mFrustum[p][0] * x +
-                            mFrustum[p][1] * y +
-                            mFrustum[p][2] * z +
-                            mFrustum[p][3] < 0)
-                    {
+            if (_flags & fUseFrustumCulling) {
+                for (p = 0; p < 6; ++p) {
+                    if (((mFrustum[p][0] * x) + (mFrustum[p][1] * y) + (mFrustum[p][2] * z) + mFrustum[p][3]) < 0) {
                         _particle[i].setActive(false);
                         break;
                     }