[Add] Documentation for fonts.

src/font.c

@@ -24,28 +24,30 @@
 #include "log.h"
 #include "pack.h"
 
-#define FONT_DEF  "../dat/font.ttf"
+#define FONT_DEF  "../dat/font.ttf" /**< Default font path. */
 
 /* Default font. */
-glFont gl_defFont;
+glFont gl_defFont;    /**< Default font. */
-glFont gl_smallFont;
+glFont gl_smallFont;  /**< Small font. */
 
 static void glFontMakeDList(FT_Face face, char ch,
                             GLuint list_base, GLuint* tex_base,
                             int* width_base);
 
-static int pot(int n);
 
-/* Get the closest power of two. */
+/**
-static int pot(int n) {
+ * @fn void gl_print(const glFont* ft_font, const double x, const double y,
-  int i = 1;
+ *             const glColour* c, const char* fmt, ...)
-  while(i < n)
+ *
-    i<<=1;
+ * @brief Print text on screen like printf.
-  return i;
+ *
-}
+ * Defaults ft_font to gl_defFont if NULL.
-
+ *    @param ft_font Font to use (NULL means gl_defFont).
-/* Print text on screen! YES!!!! Just like printf! But different! */
+ *    @param x X position to put text at.
-/* Defaults ft_font to gl_defFont if NULL. */
+ *    @param y Y position to put text at.
+ *    @param c Colour to use (uses white if NULL).
+ *    @param fmt String formatted like printf to print. *
+ */
 void gl_print(const glFont* ft_font, const double x, const double y,
               const glColour* c, const char* fmt, ...) {
   /*float h = ft_font->h / .63; // Slightly increases font size. */
@@ -80,8 +82,19 @@ void gl_print(const glFont* ft_font, const double x, const double y,
   gl_checkErr();
 }
 
-/* Acts just like gl_print, but prints to a max length of max. */
+/**
-/* Return the amount of characters we had to suppress. */
+ * @fn int gl_printMax(const glFont* ft_font, const int max,
+ *         const double x, const double y, const glColour* c, const char* fmt, ...)
+ *
+ * @brief Act like gl_print but stops displaying text after reaching a certain length.
+ *    @param ft_font Font to use (Null means use gl_defFont).
+ *    @param max Maximum length to reach.
+ *    @param x X position to display text at.
+ *    @param y Y position to display text at.
+ *    @param c Colour to use (NULL defaults to white).
+ *    @param fmt String to display formatted like printf.
+ *    @return The number of characters it had to suppress.
+ */
 int gl_printMax(const glFont* ft_font, const int max,
                 const double x, const double y, const glColour* c, const char* fmt, ...) {
   /*float h = ft_font->h / .63; // Slightly increases font size. */
@@ -131,7 +144,21 @@ int gl_printMax(const glFont* ft_font, const int max,
   return ret;
 }
 
-/* Acts just like gl_printMax, but centers the text in the width. */
+/**
+ * @fn int gl_printMid(const glFont* ft_font, const int width, double x, const double y,
+ *               const glColour* c, const char* fmt, ...)
+ *
+ * @brief Display text centered in position and width.
+ *
+ * Will truncate if text is too long.
+ *    @param ft_font Font to use (NULL defaults to gl_defFont).
+ *    @param width Width of area to center in.
+ *    @param x X Position to display text at.
+ *    @param y Y Position to display text at.
+ *    @param c Colour to use for text (NULL defaults to white).
+ *    @param fmt Text to display formatted string like printf.
+ *    @return The number of characters it had to truncate.
+ */
 int gl_printMid(const glFont* ft_font, const int width, double x, const double y,
                 const glColour* c, const char* fmt, ...) {
   /*float h = ft_font->h / .63; // Slightly increases font size. */
@@ -186,7 +213,22 @@ int gl_printMid(const glFont* ft_font, const int width, double x, const double y
   return ret;
 }
 
-/* Print text with line breaks included to a max width and height precet. */
+/**
+ * @fn int gl_printText(const glFont* ft_font, const int width, const int height,
+ *                double bx, double by, glColour* c, const char* fmt, ...)
+ *
+ * @brief Print a block of text that fits in the dimensions given.
+ *
+ * Positions are based on origin being top-left.
+ *    @param ft_font Font to use (NULL defaults to gl_defFont).
+ *    @param width Maximum width to print to.
+ *    @param height Maximum height to print to.
+ *    @param bx X position to display text at.
+ *    @param by Y position to display text at.
+ *    @param c Colour to use (NULL defaults to white).
+ *    @param fmt Text to display formatted like printf.
+ *    @return 0 on success.
+ */
 int gl_printText(const glFont* ft_font, const int width, const int height,
                  double bx, double by, glColour* c, const char* fmt, ...) {
 
@@ -271,7 +313,16 @@ int gl_printText(const glFont* ft_font, const int width, const int height,
   return ret;
 }
 
-/* Get the width of the text about to be printed. */
+/**
+ * @fn int gl_printWidth(const glFont* ft_font, const char* fmt, ...)
+ *
+ * @brief Get the width that it would take to print some text.
+ *
+ * Does not display text on screen.
+ *    @param ft_font Font to use (NULL defaults to gl_defFont).
+ *    @param fmt Text to calculate the length of.
+ *    @return The length of the text in pixels.
+ */
 int gl_printWidth(const glFont* ft_font, const char* fmt, ...) {
   int i, n;
   char txt[256]; /* Holds the string. */
@@ -293,6 +344,18 @@ int gl_printWidth(const glFont* ft_font, const char* fmt, ...) {
   return n;
 }
 
+/**
+ * @fn int gl_printHeight(const glFont* ft_font, const int width,
+ *                 const char* fmt, ...)
+ * 
+ * @brief Get the height of the text if it were printed.
+ *
+ * Does not display the text on screen.
+ *    @param ft_font Font to use (NULL defaults to gl_defFont).
+ *    @param width Width to jump to next line once reached.
+ *    @param fmt Text to get the height of in printf format.
+ *    @return The heiht of the text.
+ */
 int gl_printHeight(const glFont* ft_font, const int width,
                   const char* fmt, ...) {
   
@@ -337,9 +400,17 @@ int gl_printHeight(const glFont* ft_font, const int width,
   return (int)(y - 0.5*(double)ft_font->h);
 }
 
-/* ================ */
+/* ================
-/* FONT! */
+ * FONT!
-/* ================ */
+ * ================
+ */
+
+/**
+ * @fn static void glFontMakeDList(FT_Face face, char ch, GLuint list_base,
+ *                           GLuint* tex_base, int* width_base)
+ * 
+ * @brief Makes the font display list.
+ */
 static void glFontMakeDList(FT_Face face, char ch, GLuint list_base,
                             GLuint* tex_base, int* width_base) {
   FT_Glyph glyph;
@@ -363,8 +434,8 @@ static void glFontMakeDList(FT_Face face, char ch, GLuint list_base,
   bitmap = bitmap_glyph->bitmap; /* To simplify. */
 
   /* Need the POT wrapping for GL. */
-  w = pot(bitmap.width);
+  w = gl_pot(bitmap.width);
-  h = pot(bitmap.rows);
+  h = gl_pot(bitmap.rows);
 
   /* Memory for textured data. */
   /* Bitmap is useing two channels, one for luminosity and one for alpha. */
@@ -422,13 +493,21 @@ static void glFontMakeDList(FT_Face face, char ch, GLuint list_base,
   gl_checkErr();
 }
 
+/**
+ * @fn void gl_fontInit(glFont* font, const char* fname, const unsigned int h)
+ *
+ * @brief Initializes a font.
+ *    @param font Font to load (NULL defaults to gl_defFont).
+ *    @param fname Name of the font (from inside packfile, NULL defaults to default font).
+ *    @param h Height of the font to generate.
+ */
 void gl_fontInit(glFont* font, const char* fname, const unsigned int h) {
   uint32_t bufsize;
   int i;
 
   if(font == NULL) font = &gl_defFont;
 
-  FT_Byte* buf = pack_readfile(DATA, (fname) ? fname : FONT_DEF, &bufsize);
+  FT_Byte* buf = pack_readfile(DATA, (fname!=NULL) ? fname : FONT_DEF, &bufsize);
 
   /* Allocatagery. */
   font->textures = malloc(sizeof(GLuint)*128);
@@ -467,6 +546,12 @@ void gl_fontInit(glFont* font, const char* fname, const unsigned int h) {
   free(buf);
 }
 
+/**
+ * @fn void gl_freeFont(glFont* font)
+ *
+ * @brief Free a loaded font.
+ *    @param font Font to free.
+ */
 void gl_freeFont(glFont* font) {
   if(font == NULL) font = &gl_defFont;
   glDeleteLists(font->list_base, 128);

src/font.h

@@ -7,14 +7,14 @@
  * @brief Represents a font in memory.
  */
 typedef struct glFont_ {
-  int h; /* Height. */
+  int h;              /**< Font height. */
-  int* w;
+  int* w;             /**< Width of each font member. */
-  GLuint* textures;
+  GLuint* textures;   /**< Textures in the font. */
-  GLuint list_base;
+  GLuint list_base;   /**< Display list base. */
 } glFont;
 
-extern glFont gl_defFont; /* Default font. */
+extern glFont gl_defFont;   /**< Default font. */
-extern glFont gl_smallFont; /* Small font. */
+extern glFont gl_smallFont; /**< Small font. */
 
 /* glFont loading/freeing. */
 /* If font is NULL it uses the internal default font, same with gl_print */