From 3ffc8588634473e8ad0e332609a35c0152ec64f5 Mon Sep 17 00:00:00 2001
From: Allanis <allanis@saracraft.net>
Date: Thu, 24 Oct 2013 00:34:08 +0100
Subject: [PATCH] [Add] Documented Nebulae stuff.
---
src/nebulae.c | 158 ++++++++++++++++++++++++++++++++++++++++----------
src/opengl.h | 4 +-
2 files changed, 128 insertions(+), 34 deletions(-)
diff --git a/src/nebulae.c b/src/nebulae.c
index 5c0d056..a35acb0 100644
--- a/src/nebulae.c
+++ b/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_PUFFS 32 /* Amount of puffs to generate. */
-#define NEBULAE_PATH_BG "gen/nebu_bg_%dx%d_%02d.png"
+#define NEBULAE_Z 16 /**< Z plane. */
+#define NEBULAE_PUFFS 32 /**< Amount of puffs to generate. */
+#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 int nebu_w = 0;
-static int nebu_h = 0;
-static int nebu_pw, nebu_ph;
+static GLuint nebu_textures[NEBULAE_Z]; /**< BG Nebulae textures. */
+static int nebu_w = 0; /**< BG Nebulae width. */
+static int nebu_h = 0; /**< BG Nebulae height. */
+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 unsigned int last_render = 0;
+static int cur_nebu[2] = { 0, 1 }; /**< Nebulae currently rendering. */
+static unsigned int last_render = 0; /**< When they where last rendered. */
/* Nebuale properties. */
-static double nebu_view = 0.;
-static double nebu_dt = 0.;
+static double nebu_view = 0.; /**< How far player can see. */
+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 height; /* Height vs player. */
- int tex; /* Texture. */
+ double x; /**< X Position. */
+ double y; /**< Y Position. */
+ double height; /**< Height vs player. */
+ int tex; /**< Texture. */
} NebulaePuff;
-static NebulaePuff* nebu_puffs = NULL;
-static int nebu_npuffs = 0;
+static NebulaePuff* nebu_puffs = NULL; /**< Stack of puffs. */
+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;
diff --git a/src/opengl.h b/src/opengl.h
index 7b54d3e..02c8bf4 100644
--- a/src/opengl.h
+++ b/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);