Documentation for surfaces.

tools/qfbsp/include/surfaces.h

@@ -74,10 +74,26 @@ surface_t *AllocSurface (void);
 */
 void FreeSurface (surface_t *s);
 
+/**	Split any faces that are too big.
+
+	If the face is > options.subdivide_size in either texture direction,
+	carve off a valid sized piece and insert the remainder in the next link.
+
+	\param f		The face to subdivide.
+	\param prevptr	The address of the pointer to this face. For nice linked
+					list manipulation.
+*/
 void SubdivideFace (struct visfacet_s *f, struct visfacet_s **prevptr);
 
+/**	Free the current node tree and return a new chain of the surfaces that
+	have inside faces.
+*/
 struct surface_s *GatherNodeFaces (struct node_s *headnode);
 
+/**	Give edges to all the faces in the bsp tree.
+
+	\param headnode	The root of the bsp tree.
+*/
 void MakeFaceEdges (struct node_s *headnode);
 
 #endif//surfaces_h

tools/qfbsp/source/surfaces.c

@@ -95,12 +95,6 @@ FreeSurface (surface_t *s)
 	free (s);
 }
 
-/*
-	SubdivideFace
-
-	If the face is >256 in either texture direction, carve a valid sized
-	piece off and insert the remainder in the next link
-*/
 void
 SubdivideFace (face_t *f, face_t **prevptr)
 {
@@ -156,12 +150,6 @@ SubdivideFace (face_t *f, face_t **prevptr)
 	}
 }
 
-/*
-	GatherNodeFaces
-
-	Frees the current node tree and returns a new chain of the surfaces that
-	have inside faces.
-*/
 static void
 GatherNodeFaces_r (node_t *node)
 {
@@ -197,8 +185,6 @@ GatherNodeFaces (node_t *headnode)
 	return BuildSurfaces ();
 }
 
-//===========================================================================
-
 typedef struct hashvert_s {
 	struct hashvert_s *next;
 	vec3_t      point;
@@ -219,14 +205,14 @@ face_t     *edgefaces[MAX_MAP_EDGES][2];
 int         firstmodeledge = 1;
 int         firstmodelface;
 
-//============================================================================
-
 #define	NUM_HASH	4096
 
 hashvert_t *hashverts[NUM_HASH];
 
 static vec3_t hash_min, hash_scale;
 
+/**	Initialize the vertex hash table.
+*/
 static void
 InitHash (void)
 {
@@ -256,6 +242,11 @@ InitHash (void)
 	hvert_p = hvertex;
 }
 
+/**	Calulate the hash value of a vector.
+
+	\param vec		The vector for which to calculate the hash value.
+	\return			The hash value of the vector.
+*/
 static unsigned
 HashVec (vec3_t vec)
 {
@@ -268,6 +259,11 @@ HashVec (vec3_t vec)
 	return h;
 }
 
+/**	Get the vertex number for the vertex.
+
+	\param in		The vertex for which to get the number.
+	\param planenum The plane on which this vertex is.
+*/
 static int
 GetVertex (vec3_t in, int planenum)
 {
@@ -329,14 +325,18 @@ GetVertex (vec3_t in, int planenum)
 	return hv->num;
 }
 
-//===========================================================================
-
 int         c_tryedges;
 
-/*
-	GetEdge
+/**	Find an edge for the two vertices.
 
-	Don't allow four way edges
+	If an edge can not be found, create a new one.  Will not create a three
+	(or more) face edge.
+
+	\param p1		The first vertex.
+	\param p2		The second vertex.
+	\param f		The face of which the two vertices form an edge.
+	\return			The edge number. For a re-used edge, the edge number will
+					be negative, indicating the ends of the edge are reversed.
 */
 static int
 GetEdge (vec3_t p1, vec3_t p2, face_t *f)
@@ -348,8 +348,12 @@ GetEdge (vec3_t p1, vec3_t p2, face_t *f)
 		Sys_Error ("GetEdge: 0 contents");
 
 	c_tryedges++;
+	// get the vertex numbers for the two vertices
 	v1 = GetVertex (p1, f->planenum);
 	v2 = GetVertex (p2, f->planenum);
+
+	// search for an edge that uses the two vertices in the opposite direction
+	// but does not yet have a second face.
 	for (i = firstmodeledge; i < bsp->numedges; i++) {
 		if (v1 == bsp->edges[i].v[1] && v2 == bsp->edges[i].v[0]
 			&& !edgefaces[i][1]
@@ -359,7 +363,7 @@ GetEdge (vec3_t p1, vec3_t p2, face_t *f)
 		}
 	}
 
-	// emit an edge
+	// Create a new edge.
 	if (bsp->numedges == MAX_MAP_EDGES)
 		Sys_Error ("numedges == MAX_MAP_EDGES");
 	edge.v[0] = v1;
@@ -370,6 +374,10 @@ GetEdge (vec3_t p1, vec3_t p2, face_t *f)
 	return i;
 }
 
+/**	Give the face edges.
+
+	\param face		The face to which edges will be given.
+*/
 static void
 FindFaceEdges (face_t *face)
 {
@@ -385,6 +393,10 @@ FindFaceEdges (face_t *face)
 								  face);
 }
 
+/**	Recurse through the bsp tree, adding edges to the faces.
+
+	\param node		bsp tree node.
+*/
 static void
 MakeFaceEdges_r (node_t *node)
 {