From 8fa9b389b13297a934549dee8819e60434da9a14 Mon Sep 17 00:00:00 2001
From: Allanis <allanis@saracraft.net>
Date: Sat, 19 Oct 2013 23:14:06 +0100
Subject: [PATCH] [Add] Documentation for fonts.
---
src/font.c | 135 +++++++++++++++++++++++++++++++++++++++++++----------
src/font.h | 12 ++---
2 files changed, 116 insertions(+), 31 deletions(-)
diff --git a/src/font.c b/src/font.c
index 52e133a..ddd7b22 100644
--- a/src/font.c
+++ b/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_smallFont;
+glFont gl_defFont; /**< Default font. */
+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) {
- int i = 1;
- while(i < n)
- i<<=1;
- return i;
-}
-
-/* Print text on screen! YES!!!! Just like printf! But different! */
-/* Defaults ft_font to gl_defFont if NULL. */
+/**
+ * @fn void gl_print(const glFont* ft_font, const double x, const double y,
+ * const glColour* c, const char* fmt, ...)
+ *
+ * @brief Print text on screen like printf.
+ *
+ * Defaults ft_font to gl_defFont if NULL.
+ * @param ft_font Font to use (NULL means gl_defFont).
+ * @param x X position to put text at.
+ * @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);
- h = pot(bitmap.rows);
+ w = gl_pot(bitmap.width);
+ 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);
diff --git a/src/font.h b/src/font.h
index 8f6cecc..6ecc703 100644
--- a/src/font.h
+++ b/src/font.h
@@ -7,14 +7,14 @@
* @brief Represents a font in memory.
*/
typedef struct glFont_ {
- int h; /* Height. */
- int* w;
- GLuint* textures;
- GLuint list_base;
+ int h; /**< Font height. */
+ int* w; /**< Width of each font member. */
+ GLuint* textures; /**< Textures in the font. */
+ GLuint list_base; /**< Display list base. */
} glFont;
-extern glFont gl_defFont; /* Default font. */
-extern glFont gl_smallFont; /* Small font. */
+extern glFont gl_defFont; /**< Default font. */
+extern glFont gl_smallFont; /**< Small font. */
/* glFont loading/freeing. */
/* If font is NULL it uses the internal default font, same with gl_print */