[Add] Documented Nebulae stuff.

src/nebulae.c

@@ -1,3 +1,9 @@
+/**
+ * @file nebulae.c
+ *
+ * @brief Handle rendering and generating nebulae.
+ */
+
 #include <errno.h>
 #include "nebulae.h"
 
@@ -13,41 +19,47 @@
 #include "pause.h"
 #include "perlin.h"
 
-#define NEBULAE_Z             16   /* Z plane. */
+#define NEBULAE_Z             16    /**< Z plane. */
-#define NEBULAE_PUFFS         32  /* Amount of puffs to generate. */
+#define NEBULAE_PUFFS         32    /**< Amount of puffs to generate. */
-#define NEBULAE_PATH_BG       "gen/nebu_bg_%dx%d_%02d.png"
+#define NEBULAE_PATH_BG       "gen/nebu_bg_%dx%d_%02d.png"  /**< Nebulae path format. */
 
-#define NEBULAE_PUFF_BUFFER   300 /* Nebulae buffer. */
+#define NEBULAE_PUFF_BUFFER   300 /**< Nebulae buffer. */
 
 /* Extern. */
 extern double gui_xoff, gui_yoff;
 extern Vec2 shake_pos;
 
 /* The nebulae textures. */
-static GLuint nebu_textures[NEBULAE_Z];
+static GLuint nebu_textures[NEBULAE_Z]; /**< BG Nebulae textures. */
-static int nebu_w = 0;
+static int nebu_w = 0;                  /**< BG Nebulae width. */
-static int nebu_h = 0;
+static int nebu_h = 0;                  /**< BG Nebulae height. */
-static int nebu_pw, nebu_ph;
+static int nebu_pw;                     /**< BG Padded Nebulae width */
+static int nebu_ph;                     /**< BG Padded Nebulae height. */
 
 /* Information on rendering. */
-static int cur_nebu[2] = { 0, 1 };
+static int cur_nebu[2] = { 0, 1 };      /**< Nebulae currently rendering. */
-static unsigned int last_render = 0;
+static unsigned int last_render = 0;    /**< When they where last rendered. */
 
 /* Nebuale properties. */
-static double nebu_view = 0.;
+static double nebu_view = 0.;           /**< How far player can see. */
-static double nebu_dt   = 0.;
+static double nebu_dt   = 0.;           /**< How fast nebulae changes. */
 
 /* Puff textures. */
-static glTexture* nebu_pufftexs[NEBULAE_PUFFS];
+static glTexture* nebu_pufftexs[NEBULAE_PUFFS]; /**< Nebulae puffs. */
 
-/* Puff handling. */
+/**
+ * @struct NebulaePuff
+ *
+ * @brief Represents a nebulae puff.
+ */
 typedef struct NebulaePuff_ {
-  double x, y;          /* Position. */
+  double x;             /**< X Position. */
-  double height;        /* Height vs player. */
+  double y;             /**< Y Position. */
-  int tex;              /* Texture. */
+  double height;        /**< Height vs player. */
+  int tex;              /**< Texture. */
 } NebulaePuff;
-static NebulaePuff* nebu_puffs = NULL;
+static NebulaePuff* nebu_puffs = NULL;    /**< Stack of puffs. */
-static int nebu_npuffs = 0;
+static int nebu_npuffs = 0;               /**< Number of puffs. */
 
 static int nebu_checkCompat(const char* file);
 static void nebu_loadTexture(SDL_Surface* sur, int w, int h, GLuint tex);
@@ -58,7 +70,12 @@ static int saveNebulae(float* map, const uint32_t w, const uint32_t h,
 static SDL_Surface* loadNebulae(const char* file);
 static SDL_Surface* nebu_surfaceFromNebulaeMap(float* map, const int w, const int h);
 
-/* Initialize the nebulae. */
+/**
+ * @fn int nebu_init(void)
+ *
+ * @brief Initializes the nebulae.
+ *    @return 0 on success.
+ */
 int nebu_init(void) {
   int i;
   char nebu_file[PATH_MAX];
@@ -107,7 +124,15 @@ int nebu_init(void) {
   return 0;
 }
 
-/* Load sur into tex, check for expected size of w and h. */
+/**
+ * @fn static void nebu_loadTexture(SDL_Surface* sur, int w, int h, GLuint tex)
+ *
+ * @brief Load sur into tex, check for expected size of w and h.
+ *    @param sur Surface to load into texture.
+ *    @param w Expected width of surface.
+ *    @param h Expected height of surface.
+ *    @param tex Already generated texture to load into.
+ */
 static void nebu_loadTexture(SDL_Surface* sur, int w, int h, GLuint tex) {
   SDL_Surface* nebu_sur;
 
@@ -135,7 +160,11 @@ static void nebu_loadTexture(SDL_Surface* sur, int w, int h, GLuint tex) {
   gl_checkErr();
 }
 
-/* Clean up the nebu subsystem. */
+/**
+ * @fn void nebu_exit(void)
+ *
+ * @brief Clean up the nebu subsystem.
+ */
 void nebu_exit(void) {
   int i;
 
@@ -145,7 +174,12 @@ void nebu_exit(void) {
     gl_freeTexture(nebu_pufftexs[i]);
 }
 
-/* Render the nebulae. */
+/**
+ * @fn void nebu_render(const double dt)
+ *
+ * @brief Render the nebulae.
+ *    @param dt Current delta tick.
+ */
 void nebu_render(const double dt) {
   unsigned int t;
   double ndt;
@@ -258,6 +292,12 @@ void nebu_render(const double dt) {
   nebu_renderPuffs(dt, 1);
 }
 
+/**
+ * @fn void nebu_renderOverlay(const double dt)
+ *
+ * @brief Renders the nebulae overlay (hides what player can't see).
+ *    @param dt Current delta tick.
+ */
 void nebu_renderOverlay(const double dt) {
 #define ANG45   0.70710678118654757
 #define COS225  0.92387953251128674
@@ -352,7 +392,13 @@ void nebu_renderOverlay(const double dt) {
 #undef SIN225
 }
 
-/* Render the puffs. */
+/**
+ * @fn void nebu_renderPuffs(const double dt, int below_player)
+ *
+ * @brief Render the puffs.
+ *    @param dt Current delta tick.
+ *    @param below_player Render the puffs below player or above?
+ */
 void nebu_renderPuffs(const double dt, int below_player) {
   int i;
 
@@ -387,7 +433,13 @@ void nebu_renderPuffs(const double dt, int below_player) {
   }
 }
 
-/* Prepare the nebulae. */
+/**
+ * @fn void nebu_prep(double density, double volatility)
+ *
+ * @brief Prepares the nebulae to be rendered.
+ *    @param density Density of the nebulae (0-1000).
+ *    @param volatility Volatility of the nebulae (0-1000).
+ */
 void nebu_prep(double density, double volatility) {
   (void)volatility;
   int i;
@@ -410,12 +462,20 @@ void nebu_prep(double density, double volatility) {
   }
 }
 
-/* Force generation of new nebulae. */
+/**
+ * @fn void nebu_forceGenerate(void)
+ *
+ * @brief Force generation of new nebulae on init.
+ */
 void nebu_forceGenerate(void) {
   nebu_w = nebu_h = -9; /* Magic numbers. ^.^ */
 }
 
-/* Generate the nebulae. */
+/**
+ * @fn static int nebu_generate(void)
+ * @brief Generates the nebulae.
+ *    @return 0 on success.
+ */
 static int nebu_generate(void) {
   int i;
   float* nebu;
@@ -442,7 +502,11 @@ static int nebu_generate(void) {
   return ret;
 }
 
-/* Generate the nebulae puffs. */
+/**
+ * @fn static void nebu_generatePuffs(void)
+ *
+ * @brief Generate nebulae puffs.
+ */
 static void nebu_generatePuffs(void) {
   int i;
   int w, h;
@@ -462,14 +526,30 @@ static void nebu_generatePuffs(void) {
   }
 }
 
-/* Check the validity of a nebulae. 0 on success. */
+/**
+ * @fn static int nebu_checkCompat(const char* file)
+ *
+ * @brief Check the validity of a nebulae.
+ *    @param file Path of the nebulae to check (relative to base directory).
+ *    @return 0 on success.
+ */
 static int nebu_checkCompat(const char* file) {
   if(lfile_fileExists(file) == 0) /* First check to see if file exists. */
     return -1;
   return 0;
 }
 
-/* Save a nebulae. */
+/**
+ * @fn static int saveNebulae(float* map, const uint32_t w, const uint32_t h,
+ *                  const char* file)
+ * 
+ * @brief Save a nebulae.
+ *    @param map Nebulae map to save.
+ *    @param w Width of nebulae map.
+ *    @param h Height of nebulae map.
+ *    @param file Path to save into.
+ *    @return 0 on success.
+ */
 static int saveNebulae(float* map, const uint32_t w, const uint32_t h,
     const char* file) {
   
@@ -491,7 +571,13 @@ static int saveNebulae(float* map, const uint32_t w, const uint32_t h,
   return ret;
 }
 
-/* Load the nebulae from file. */
+/**
+ * @fn static SDL_Surface* loadNebulae(const char* file)
+ *
+ * @brief Loads the nebulae from file.
+ *    @param file Path of the nebulae to load. Relative to base directory.
+ *    @return An SDL surface with the nebulae.
+ */
 static SDL_Surface* loadNebulae(const char* file) {
   char file_path[PATH_MAX];
   SDL_Surface* sur;
@@ -508,7 +594,15 @@ static SDL_Surface* loadNebulae(const char* file) {
   return sur;
 }
 
-/* Generate an SDL_Surface from a 2d nebulae map. */
+/**
+ * @fn SDL_Surface* nebu_surfaceFromNebulaeMap(float* map, const int w, const int h)
+ *
+ * @brief Generate an SDL_Surface from a 2d nebulae map.
+ *    @param map Nebulae map to use.
+ *    @param w Map width.
+ *    @param h Map height.
+ *    @return An SDL Surface with the nebulae.
+ */
 SDL_Surface* nebu_surfaceFromNebulaeMap(float* map, const int w, const int h) {
   int i;
   SDL_Surface* sur;

src/opengl.h

@@ -80,11 +80,11 @@ typedef struct glTexture_ {
   GLuint texture;     /**< The opengl texture itself. */
   uint8_t* trans;     /**< Maps the transparency. */
 
-  /* Properies */
+  /* Properties */
   uint8_t flags;      /**< Flags used for texture properties. */
 } glTexture;
 
-/* glTextyre loading/freeing. */
+/* glTexture loading/freeing. */
 SDL_Surface* gl_prepareSurface(SDL_Surface* surface); /* Only preps it. */
 glTexture* gl_loadImage(SDL_Surface* surface); /* Frees the surface. */
 glTexture* gl_newImage(const char* path);