bit more cleanup and some documentation

include/QF/draw.h

@@ -29,28 +29,178 @@
 #ifndef _DRAW_H
 #define _DRAW_H
 
+/** \defgroup video Video Syb-sytem */
+//@{
+
+/** \defgroup video_renderer Renderer Sub-system */
+//@{
+
+/** \defgroup video_renderer_draw Generic draw functions */
+//@{
+
 #include "QF/wad.h"
 
 extern byte *draw_chars;
 
+/** Initialize the draw stuff.
+*/
 void Draw_Init (void);
-void Draw_InitText (void);
-void Draw_Character (int x, int y, unsigned int num);
-void Draw_ConsoleBackground (int lines, byte alpha);
-void Draw_Crosshair (void);
-void Draw_CrosshairAt (int ch, int x, int y);
-void Draw_TileClear (int x, int y, int w, int h);
-void Draw_Fill (int x, int y, int w, int h, int c);
-void Draw_FadeScreen (void);
+
+/** Draws one 8*8 graphics character with 0 being transparent.
+	It can be clipped to the top of the screen to allow the console to be
+	smoothly scrolled off.
+	\param x	horizontal location of the top left corner of the character.
+	\param y	vertical location of the top left corner of the character.
+	\param chr	8 bit character to draw.
+	\note		The character drawn is from the quake character set, which is
+				(by default) standard ascii for 0x20-0x7e (white). 0xa0-0xfe is
+				also standard ascii (brown). 0x01-0x1f and 0x80-0x9f are
+				various drawing characters, and 0x7f is a backwards arrow.
+*/
+void Draw_Character (int x, int y, unsigned int ch);
+
+/** Draws a character string to the screen.
+	No line wrapping is performed.
+	\param x	horizontal location of the top left corner of the character.
+	\param y	vertical location of the top left corner of the character.
+	\param str	8 bit character string to draw.
+	\note		See Draw_Character() for character set description.
+				String is normal nul terminated C string.
+*/
 void Draw_String (int x, int y, const char *str);
+
+/** Draws a character sub-string to the screen.
+	No line wrapping is performed.
+	\param x	horizontal location of the top left corner of the character.
+	\param y	vertical location of the top left corner of the character.
+	\param str	8 bit character string to draw.
+	\param count Maximum characters of the string to draw.
+	\note		See Draw_Character() for character set description.
+				Draws up to \p count characters, or stops at the first nul
+				character.
+*/
 void Draw_nString (int x, int y, const char *str, int count);
+
+/** Draws a character string to the screen.
+	No line wrapping is performed.
+	\param x	horizontal location of the top left corner of the character.
+	\param y	vertical location of the top left corner of the character.
+	\param str	8 bit character string to draw.
+	\note		See Draw_Character() for character set description.
+				String is normal nul terminated C string.
+				Characters of the string are forced to have their high bit set
+				(ie, they will be in the range 0x80-0xff).
+*/
 void Draw_AltString (int x, int y, const char *str);
 
-void Draw_ClearCache (void);
-qpic_t *Draw_PicFromWad (const char *name);
-qpic_t *Draw_CachePic (const char *path, qboolean alpha);
-void Draw_Pic (int x, int y, qpic_t *pic);
-void Draw_SubPic(int x, int y, qpic_t *pic, int srcx, int srcy, int width, int height);
+/** Draw the console background with various optional effects.
+	\param lines Vertical size in pixels of the console.
+	\param alpha Console transparency level (255 = opaque).
+	\note		\p alpha is effective only in the OpenGL renderer. Effectively
+				255 (opaque) for the software renderer.
+
+	\c gl_conspin causes the background to spin.
+
+	\c gl_constretch causes the background to stretch rather than slide.
+*/
+void Draw_ConsoleBackground (int lines, byte alpha);
+
+/** Draw a crosshair at the center of the screen.
+	\c crosshair specifies which crosshair (1 = '+', 2 = large 'x' shape,
+	3 = fancy '+' shape)
+	\c cl_crossx and \c cl_crossy offset the crosshair from the center of the
+	screen.
+*/
+void Draw_Crosshair (void);
+
+/** Draw the specified crosshair on the screen.
+	\param ch	crosshair to draw
+	\param x	horizontal position of the center of the crosshair.
+	\param y	vertical position of the center of the crosshair.
+
+	See Draw_Crosshair() for description of crosshair values.
+*/
+void Draw_CrosshairAt (int ch, int x, int y);
+
+/** Clear a rectangle with a tiled background.
+	\param x	horizontal position of the upper left corner of the rectangle
+	\param y	horizontal position of the upper left corner of the rectangle
+	\param w	width of the rectangle
+	\param h	height of the rectangle
+
+	The background used is the "backtile" WAD lump.
+*/
+void Draw_TileClear (int x, int y, int w, int h);
+
+/** Clear a rectangle with a solid color.
+	\param x	horizontal position of the upper left corner of the rectangle
+	\param y	horizontal position of the upper left corner of the rectangle
+	\param w	width of the rectangle
+	\param h	height of the rectangle
+	\param c	8 bit color index.
+
+	The color comes from the quake palette.
+*/
+void Draw_Fill (int x, int y, int w, int h, int c);
+
+/** Draw a text box on the screen
+	\param x	horizontal location of the upper left corner of the box
+	\param y	vertical location of the upper left corner of the box
+	\param width horizontal size in character cells of the region
+	\param height vertical size in character cells of the region
+	\param alpha transparency of the box
+*/
 void Draw_TextBox (int x, int y, int width, int lines, byte alpha);
 
+/** Darken the screen.
+*/
+void Draw_FadeScreen (void);
+
+/** \defgroup video_renderer_draw_qpic QPic functions */
+//@{
+/** Clear out the cached qpic textures.
+*/
+void Draw_ClearCache (void);
+
+/** Load a qpic from the filesystem.
+	\param path	path of the file within the quake filesystem
+	\param alpha transparency level of the pic.
+	\return		pointer qpic data.
+	\note		Up to MAX_CACHED_PICS qpics can be loaded at a time this way
+*/
+qpic_t *Draw_CachePic (const char *path, qboolean alpha);
+
+/** Load a qpic from gfx.wad.
+	\param name	name of the was lump to load
+	\return		pointer qpic data.
+*/
+qpic_t *Draw_PicFromWad (const char *name);
+
+/** Draw a qpic to the screen
+	\param x	horizontal location of the upper left corner of the qpic
+	\param y	vertical location of the upper left corner of the qpic
+	\param pic	qpic to draw
+*/
+void Draw_Pic (int x, int y, qpic_t *pic);
+
+/** Draw a sub-region of a qpic to the screan
+	\param x	horizontal screen location of the upper left corner of the
+				sub-region
+	\param y	vertical screen location of the upper left corner of the
+				sub-region
+	\param pic	qpic to draw
+	\param srcx	horizontal qpic location of the upper left corner of the
+				sub-region
+	\param srcy	vertical qpic location of the upper left corner of the
+				sub-region
+	\param width horizontal size of the sub-region to be drawn
+	\param width vertical size of the sub-region to be drawn
+*/
+void Draw_SubPic(int x, int y, qpic_t *pic, int srcx, int srcy, int width, int height);
+//@}
+
+//@}
+//@}
+//@}
+
 #endif // _DRAW_H

libs/video/renderer/gl/gl_draw.c

@@ -123,53 +123,38 @@ static int		numcachepics;
 static byte		menuplyr_pixels[4096];
 
 
-void
+static void
 Draw_InitText (void)
 {
 	int		i;
 
-	if (r_init) {
-		if (vaelements > 3) {
-			tVAsize = vaelements - (vaelements % 4);
-		} else if (vaelements >= 0) {
-			tVAsize = 2048;
-		} else
-			tVAsize = 0;
+	if (vaelements > 3) {
+		tVAsize = vaelements - (vaelements % 4);
+	} else if (vaelements >= 0) {
+		tVAsize = 2048;
+	} else
+		tVAsize = 0;
 
-		if (tVAsize) {
-			Con_Printf ("Text: %i maximum vertex elements.\n", tVAsize);
+	if (tVAsize) {
+		Con_Printf ("Text: %i maximum vertex elements.\n", tVAsize);
 
-			if (textVertices)
-				free (textVertices);
-			textVertices = calloc (tVAsize, 2 * sizeof (float));
-
-			if (textCoords)
-				free (textCoords);
-			textCoords = calloc (tVAsize, 2 * sizeof (float));
-
-			qfglTexCoordPointer (2, GL_FLOAT, 0, textCoords);
-			qfglVertexPointer (2, GL_FLOAT, 0, textVertices);
-			if (tVAindices)
-				free (tVAindices);
-			tVAindices = (int *) calloc (tVAsize, sizeof (int));
-			for (i = 0; i < tVAsize; i++)
-				tVAindices[i] = i;
-		} else {
-			Con_Printf ("Text: Vertex Array use disabled.\n");
-		}
-	} else {
-		if (textVertices) {
+		if (textVertices)
 			free (textVertices);
-			textVertices = 0;
-		}
-		if (textCoords) {
+		textVertices = calloc (tVAsize, 2 * sizeof (float));
+
+		if (textCoords)
 			free (textCoords);
-			textCoords = 0;
-		}
-		if (tVAindices) {
+		textCoords = calloc (tVAsize, 2 * sizeof (float));
+
+		qfglTexCoordPointer (2, GL_FLOAT, 0, textCoords);
+		qfglVertexPointer (2, GL_FLOAT, 0, textVertices);
+		if (tVAindices)
 			free (tVAindices);
-			tVAindices = 0;
-		}
+		tVAindices = (int *) calloc (tVAsize, sizeof (int));
+		for (i = 0; i < tVAsize; i++)
+			tVAindices[i] = i;
+	} else {
+		Con_Printf ("Text: Vertex Array use disabled.\n");
 	}
 }
 
@@ -387,6 +372,8 @@ Draw_Init (void)
 	// LordHavoc: call init code for other GL renderer modules
 	glrmain_init ();
 	gl_lightmap_init ();
+
+	Draw_InitText ();
 }
 
 #define CELL_SIZE 0.0625
@@ -402,12 +389,12 @@ flush_text (void)
 }
 
 static inline void
-queue_character (float x, float y, int num)
+queue_character (float x, float y, int chr)
 {
 	float		frow, fcol;
 
-	frow = (num >> 4) * CELL_SIZE;
-	fcol = (num & 15) * CELL_SIZE;
+	frow = (chr >> 4) * CELL_SIZE;
+	fcol = (chr & 15) * CELL_SIZE;
 
 	*tV++ = x;
 	*tV++ = y;
@@ -443,23 +430,23 @@ tVA_increment (void)
 	smoothly scrolled off.
 */
 void
-Draw_Character (int x, int y, unsigned int num)
+Draw_Character (int x, int y, unsigned int chr)
 {
-	if (num == 32)
+	chr &= 255;
+
+	if (chr == 32)
 		return;							// space
 	if (y <= -8)
 		return;							// totally off screen
 
-	num &= 255;
-
-	queue_character ((float) x, (float) y, num);
+	queue_character ((float) x, (float) y, chr);
 	tVA_increment ();
 }
 
 void
 Draw_String (int x, int y, const char *str)
 {
-	unsigned char	num;
+	unsigned char	chr;
 	float			x1, y1;
 
 	if (!str || !str[0])
@@ -471,8 +458,8 @@ Draw_String (int x, int y, const char *str)
 	y1 = (float) y;
 
 	while (*str) {
-		if ((num = *str++) != 32) {		// Don't render spaces
-			queue_character (x1, y1, num);
+		if ((chr = *str++) != 32) {		// Don't render spaces
+			queue_character (x1, y1, chr);
 			tVA_increment ();
 		}
 		x1 += 8.0;
@@ -482,7 +469,7 @@ Draw_String (int x, int y, const char *str)
 void
 Draw_nString (int x, int y, const char *str, int count)
 {
-	unsigned char	num;
+	unsigned char	chr;
 	float			x1, y1;
 
 	if (!str || !str[0])
@@ -494,8 +481,8 @@ Draw_nString (int x, int y, const char *str, int count)
 	y1 = (float) y;
 
 	while (count-- && *str) {
-		if ((num = *str++) != 32) {		// Don't render spaces
-			queue_character (x1, y1, num);
+		if ((chr = *str++) != 32) {		// Don't render spaces
+			queue_character (x1, y1, chr);
 			tVA_increment ();
 		}
 		x1 += 8.0;
@@ -505,7 +492,7 @@ Draw_nString (int x, int y, const char *str, int count)
 void
 Draw_AltString (int x, int y, const char *str)
 {
-	unsigned char	num;
+	unsigned char	chr;
 	float			x1, y1;
 
 	if (!str || !str[0])
@@ -517,8 +504,8 @@ Draw_AltString (int x, int y, const char *str)
 	y1 = (float) y;
 
 	while (*str) {
-		if ((num = *str++ | 0x80) != (0x80 | 32)) {		// Don't render spaces
-			queue_character (x1, y1, num);
+		if ((chr = *str++ | 0x80) != (0x80 | 32)) {		// Don't render spaces
+			queue_character (x1, y1, chr);
 			tVA_increment ();
 		}
 		x1 += 8.0;

libs/video/renderer/gl/gl_rmisc.c

@@ -161,7 +161,6 @@ R_Init (void)
 	r_init = 1;
 	R_InitParticles ();
 	R_InitSprites ();
-	Draw_InitText ();
 }
 
 void

libs/video/renderer/r_screen.c

@@ -322,7 +322,7 @@ MipColor (int r, int g, int b)
 // in draw.c
 
 static void
-SCR_DrawCharToSnap (int num, byte * dest, int width)
+SCR_DrawCharToSnap (int num, byte *dest, int width)
 {
 	byte       *source;
 	int         col, row, drawline, x;

libs/video/renderer/sw/draw.c

@@ -200,25 +200,25 @@ Draw_Init (void)
 	smoothly scrolled off.
 */
 inline void
-Draw_Character (int x, int y, unsigned int num)
+Draw_Character (int x, int y, unsigned int chr)
 {
 	byte       *dest;
 	byte       *source;
 	int         drawline;
 	int         row, col;
 
-	num &= 255;
+	chr &= 255;
 
 	if (y <= -8)
 		return;							// totally off screen
 
 	if (y > (int) vid.height - 8 || x < 0 || x > (int) vid.width - 8)
 		return;
-	if (num < 0 || num > 255)
+	if (chr < 0 || chr > 255)
 		return;
 
-	row = num >> 4;
-	col = num & 15;
+	row = chr >> 4;
+	col = chr & 15;
 	source = draw_chars + (row << 10) + (col << 3);
 
 	if (y < 0) {						// clipped

libs/video/renderer/sw32/draw.c

@@ -200,24 +200,24 @@ Draw_Init (void)
 	smoothly scrolled off.
 */
 void
-Draw_Character (int x, int y, unsigned int num)
+Draw_Character (int x, int y, unsigned int chr)
 {
 	byte       *source;
 	int         drawline;
 	int         row, col;
 
-	num &= 255;
+	chr &= 255;
 
 	if (y <= -8)
 		return;							// totally off screen
 
 	if (y > (int) vid.height - 8 || x < 0 || x > (int) vid.width - 8)
 		return;
-	if (num < 0 || num > 255)
+	if (chr < 0 || chr > 255)
 		return;
 
-	row = num >> 4;
-	col = num & 15;
+	row = chr >> 4;
+	col = chr & 15;
 	source = draw_chars + (row << 10) + (col << 3);
 
 	if (y < 0) {						// clipped