From 7370746bcad955eb813418d0e1d5686f22c99369 Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Sat, 4 May 2019 23:34:15 +0300
Subject: [PATCH] Add a bunch of comments to the Mesh class in the Blender
 exporter

---
 blender/io_mspgl/mesh.py | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/blender/io_mspgl/mesh.py b/blender/io_mspgl/mesh.py
index 44fbdcb0..b58637b7 100644
--- a/blender/io_mspgl/mesh.py
+++ b/blender/io_mspgl/mesh.py
@@ -167,12 +167,17 @@ class Mesh:
 		self.tbn_vecs = mesh.tbn_vecs
 		self.vertex_groups = mesh.vertex_groups
 
+		# Clone basic data
 		self.vertices = [Vertex(v) for v in self.vertices]
+		for v in self.vertices:
+			v.groups = [VertexGroup(g) for g in v.groups]
+
 		self.faces = [Face(f) for f in self.polygons]
 		self.edges = [Edge(e) for e in self.edges]
 		self.loops = self.loops[:]
-
 		self.materials = self.materials[:]
+
+		# Clone only the desired UV layers
 		if self.use_uv=='NONE' or not self.uv_layers:
 			self.uv_layers = []
 		else:
@@ -182,15 +187,15 @@ class Mesh:
 			if self.use_uv=='UNIT0':
 				self.uv_layers = [self.uv_layers[0]]
 
+			# Assign texture unit numbers to UV layers that lack one
 			next_unit = max((u.unit+1 for u in self.uv_layers if u.unit is not None), default=0)
 			for u in self.uv_layers:
 				if not u.unit:
 					u.unit = next_unit
 					next_unit += 1
 
-		for v in self.vertices:
-			v.groups = [VertexGroup(g) for g in v.groups]
-
+		# Rewrite links between elements to point to cloned data, or create links
+		# where they don't exist
 		edge_map = {e.key: e for e in self.edges}
 		for f in self.faces:
 			if len(f.vertices)>4:
@@ -210,6 +215,7 @@ class Mesh:
 			for v in e.vertices:
 				v.edges.append(e)
 
+		# Store loose edges as lines
 		if self.use_lines:
 			self.lines = [Line(e) for e in self.edges if not e.faces]
 		else:
@@ -229,6 +235,8 @@ class Mesh:
 			if u.name!=other.uv_layers[i].name:
 				raise ValueError("Meshes have incompatible UV layers")
 
+		# Merge materials and form a lookup from source material indices to the
+		# merged material list
 		material_map = []
 		for m in other.materials:
 			if m in self.materials:
@@ -237,6 +245,8 @@ class Mesh:
 				material_map.append(len(self.materials))
 				self.materials.append(m)
 
+		# Append data and adjust indices where necessary.  Since the data is
+		# spliced from the source mesh, rebuilding references is not necessary.
 		for i, u in enumerate(self.uv_layers):
 			u.uvs += other.uv_layers[i].uvs
 
@@ -325,6 +335,8 @@ class Mesh:
 				for i in f.loop_indices:
 					layer.uvs[i] = uv
 
+		# Form a list of UV layers referenced by materials with the array atlas
+		# property set
 		array_uv_layers = [t.uv_layer for m in self.materials if m.array_atlas for t in m.texture_slots if t and t.texture_coords=='UV']
 		array_uv_layers = [u for u in self.uv_layers if u.name in array_uv_layers]
 
@@ -340,6 +352,7 @@ class Mesh:
 					for i in f.loop_indices:
 						l.uvs[i] = mathutils.Vector((*l.uvs[i], layer))
 
+		# Copy UVs from layers to faces
 		for f in self.faces:
 			for u in self.uv_layers:
 				f.uvs.append([u.uvs[i] for i in f.loop_indices])
@@ -347,6 +360,8 @@ class Mesh:
 		prog_count = len(self.uv_layers)
 		prog_step = 0
 
+		# Split by the UV layer used for TBN vectors first so connectivity
+		# remains intact for TBN vector computation
 		tbn_layer_index = -1
 		if self.tbn_vecs:
 			uv_names = [u.name for u in self.uv_layers]
@@ -360,6 +375,7 @@ class Mesh:
 				progress.pop_task()
 				prog_step = 2
 
+		# Split by the remaining UV layers
 		for i, u in enumerate(self.uv_layers):
 			if i==tbn_layer_index:
 				continue
@@ -369,8 +385,10 @@ class Mesh:
 			progress.pop_task()
 			prog_step += 1
 
+		# Copy UVs from faces to vertices
 		for v in self.vertices:
 			if v.faces:
+				# All faces still connected to the vertex have the same UV value
 				f = v.faces[0]
 				i = f.vertices.index(v)
 				v.uvs = [u[i] for u in f.uvs]
@@ -384,11 +402,13 @@ class Mesh:
 			for f in v.faces:
 				f.flag = False
 
+			# Find all groups of faces on this vertex
 			groups = []
 			for f in v.faces:
 				if not f.flag:
 					groups.append(find_group_func(v, f, *args))
 
+			# Give groups after the first separate copies of the vertex
 			for g in groups[1:]:
 				nv = Vertex(v)
 				nv.index = len(self.vertices)
@@ -400,6 +420,7 @@ class Mesh:
 						continue
 
 					if len(e_faces_in_g)<len(e.faces):
+						# Create a copy of an edge at the boundary of the group
 						ne = Edge(e)
 						ne.index = len(self.edges)
 						self.edges.append(ne)
@@ -418,6 +439,7 @@ class Mesh:
 
 					e.key = make_edge_key(e.vertices[0].index, e.vertices[1].index)
 
+				# Filter out any edges that were removed from the original vertex
 				v.edges = [e for e in v.edges if v in e.vertices]
 
 				for f in g:
@@ -466,6 +488,9 @@ class Mesh:
 				edge1 = fv[1].co-fv[0].co
 				edge2 = fv[-1].co-fv[0].co
 				if edge1.length and edge2.length:
+					# Use the angle between edges as a weighting factor.  This gives
+					# more consistent normals on bends with an inequal number of
+					# faces on each side.
 					v.normal += f.normal*edge1.angle(edge2)
 
 			if v.normal.length:
@@ -476,6 +501,8 @@ class Mesh:
 			progress.set_progress(i/len(self.vertices))
 
 	def compute_tbn(self, index, progress):
+		# This function is called at an early stage during UV preparation when
+		# face UVs are not available yet
 		layer_uvs = self.uv_layers[index].uvs
 
 		for i, v in enumerate(self.vertices):
@@ -609,6 +636,8 @@ def create_mesh_from_object(context, obj, progress):
 	progress.set_task("Preparing UVs", 0.7, 1.0)
 	mesh.prepare_uv(obj, progress)
 
+	# Discard the temporary Blender meshes after making sure there's no
+	# references to the data
 	mesh.drop_references()
 	for m in bmeshes:
 		bpy.data.meshes.remove(m)
-- 
2.43.0