Merge pull request #1047 from zeux/nicet

tangentspace: Improved tangent space generation

Author: zeux

README.md

@@ -796,6 +796,52 @@ Additionally, note that while the code above works with 32-bit OMM indices, afte
 
 When using 4-state OMMs, rasterization code produces both unknown-transparent and unknown-opaque states based on microtriangle coverage; this enables the use of forced 2-state flag during traversal for specific effects where micromap data is sufficient for reasonable quality; this is recommended for performance as this results in no any-hit invocations.
 
+### Tangent spaces
+
+Meshes that use tangent space normal maps often require per-vertex tangent vectors in addition to normals. These could be exported alongside mesh data, but this library also provides an algorithm similar to MikkTSpace that can generate them from positions, normals and texture coordinates:
+
+```c++
+std::vector<vec4> tangents(indices.size());
+meshopt_generateTangents(&tangents[0].x, &indices[0], indices.size(),
+    &vertices[0].px, vertices.size(), sizeof(Vertex), &vertices[0].nx, sizeof(Vertex), &vertices[0].tx, sizeof(Vertex));
+```
+
+For each triangle *corner* this writes a normalized tangent vector (xyz) and an orientation sign (+-1); the bitangent can be reconstructed in the shader as `cross(normal, tangent.xyz) * tangent.w`. Note that some coordinate space conventions that flip V direction in the texture space require negating orientation sign. The input can be indexed, as in the example above, or not (`indices=NULL`); this does not affect the output tangents.
+
+Because tangents are computed per corner, applying them to mesh vertices requires de-indexing the mesh and generating a new index/vertex buffer afterwards (see `Indexing` section earlier), or using indexed data and copying tangents to existing vertex data while duplicating vertices with different tangents (see `tangents` example in `demo/main.cpp`). With the indexed input, if it contains UV mirroring, vertices along the mirror edge may have different tangent spaces on different sides of the edge and need to be split - copying tangents to existing vertex data without splitting will not produce correct results.
+
+If splitting is required, it can be efficiently done with an extra pass and an index list per vertex:
+
+```c++
+// seed each vertex with one of its corner tangents; the loop below fixes any mismatches
+for (size_t i = 0; i < indices.size(); ++i)
+    vertices[indices[i]].tangent = tangents[i];
+
+std::vector<unsigned int> splits(vertices.size(), ~0u);
+
+for (size_t i = 0; i < indices.size(); ++i)
+{
+    // walk the chain of split copies looking for a vertex whose tangent matches
+    unsigned int v = indices[i];
+    while (v != ~0u && vertices[v].tangent != tangents[i])
+        v = splits[v];
+
+    // no match in chain: append a new split copy with the target tangent and chain it
+    if (v == ~0u)
+    {
+        v = unsigned(vertices.size());
+        vertices.push_back(vertices[indices[i]]);
+        vertices[v].tangent = tangents[i];
+        splits.push_back(splits[indices[i]]);
+        splits[indices[i]] = v;
+    }
+
+    indices[i] = v;
+}
+```
+
+The algorithm uses a MikkTSpace-like construction but by default, uses a modified weighting scheme that significantly improves tangent quality around beveled regions in the mesh. If the normal maps are baked from higher resolution geometry using MikkTSpace weighting, it's possible to produce MikkTSpace-compatible tangents by passing `meshopt_TangentCompatible` option as an extra argument to the function.
+
 ## Memory management
 
 Many algorithms allocate temporary memory to store intermediate results or accelerate processing. The amount of memory allocated is a function of various input parameters such as vertex count and index count. By default memory is allocated using `operator new` and `operator delete`; if these operators are overloaded by the application, the overloads will be used instead. Alternatively it's possible to specify custom allocation/deallocation functions using `meshopt_setAllocator`, e.g.
@@ -828,6 +874,7 @@ Currently, the following APIs are experimental:
 - `meshopt_encode/decodeMeshlet*` functions (`meshopt_encodeMeshlet`, `meshopt_encodeMeshletBound`, `meshopt_decodeMeshlet`, `meshopt_decodeMeshletRaw`)
 - `meshopt_extractMeshletIndices` and `meshopt_optimizeMeshletLevel` functions
 - `meshopt_opacityMap*` functions (`meshopt_opacityMapMeasure`, `meshopt_opacityMapRasterize`, `meshopt_opacityMapCompact`, `meshopt_opacityMapEntrySize`)
+- `meshopt_generateTangents` function and `meshopt_Tangent*` flags
 
 ## License
 

demo/main.cpp

@@ -1410,8 +1410,8 @@ void tangents(const Mesh& mesh)
 
 	std::vector<VertexTangent> newvertices(mesh.vertices.size());
 	std::vector<unsigned int> newindices = mesh.indices;
-	std::vector<unsigned int> splits(mesh.vertices.size(), ~0u);
 
+	// copy positions/normals/UVs (Vertex has no tangent field, so we use VertexTangent)
 	for (size_t i = 0; i < mesh.vertices.size(); ++i)
 	{
 		VertexTangent& vt = newvertices[i];
@@ -1420,37 +1420,38 @@ void tangents(const Mesh& mesh)
 		vt.px = v.px, vt.py = v.py, vt.pz = v.pz;
 		vt.nx = v.nx, vt.ny = v.ny, vt.nz = v.nz;
 		vt.tu = v.tx, vt.tv = v.ty;
-		// leave vt.txyzw as 0 as we'll fill them below
 	}
 
+	// seed each vertex with one of its corner tangents; the loop below fixes any mismatches
 	for (size_t i = 0; i < mesh.indices.size(); ++i)
 	{
+		VertexTangent& vt = newvertices[mesh.indices[i]];
 		const float* t = &tangents[i * 4];
-		unsigned int v = mesh.indices[i];
+		vt.tx = t[0], vt.ty = t[1], vt.tz = t[2], vt.tw = t[3];
+	}
 
-		// initial tangent value
-		if (newvertices[v].tw == 0.f)
-			newvertices[v].tx = t[0], newvertices[v].ty = t[1], newvertices[v].tz = t[2], newvertices[v].tw = t[3];
-		else if (newvertices[v].tx != t[0] || newvertices[v].ty != t[1] || newvertices[v].tz != t[2] || newvertices[v].tw != t[3])
-		{
-			// tangent split; we might be able to reuse previously split vertices, or might need to add a new one
-			unsigned int sv = splits[v];
-			while (sv != ~0u && (newvertices[sv].tx != t[0] || newvertices[sv].ty != t[1] || newvertices[sv].tz != t[2] || newvertices[sv].tw != t[3]))
-				sv = splits[sv];
+	std::vector<unsigned int> splits(mesh.vertices.size(), ~0u);
 
-			// need to add a new split and chain it to the existing list
-			if (sv == ~0u)
-			{
-				sv = unsigned(newvertices.size());
-				newvertices.push_back(newvertices[v]);
-				newvertices[sv].tx = t[0], newvertices[sv].ty = t[1], newvertices[sv].tz = t[2], newvertices[sv].tw = t[3];
+	for (size_t i = 0; i < mesh.indices.size(); ++i)
+	{
+		const float* t = &tangents[i * 4];
+		unsigned int v = mesh.indices[i];
 
-				splits.push_back(splits[v]);
-				splits[v] = sv;
-			}
+		// walk the chain of split copies looking for a vertex whose tangent matches
+		while (v != ~0u && (newvertices[v].tx != t[0] || newvertices[v].ty != t[1] || newvertices[v].tz != t[2] || newvertices[v].tw != t[3]))
+			v = splits[v];
 
-			newindices[i] = sv;
+		// no match in chain: append a new split copy with the target tangent and chain it
+		if (v == ~0u)
+		{
+			v = unsigned(newvertices.size());
+			newvertices.push_back(newvertices[mesh.indices[i]]);
+			newvertices[v].tx = t[0], newvertices[v].ty = t[1], newvertices[v].tz = t[2], newvertices[v].tw = t[3];
+			splits.push_back(splits[mesh.indices[i]]);
+			splits[mesh.indices[i]] = v;
 		}
+
+		newindices[i] = v;
 	}
 
 	double end = timestamp();

demo/tests.cpp

@@ -3123,6 +3123,60 @@ static void opacityMapSpecial()
 	}
 }
 
+static void tangentDegenerate()
+{
+	struct Vertex
+	{
+		float px, py, pz;
+		float nx, ny, nz;
+		float tx, ty;
+	};
+
+	const Vertex vertices[] = {
+	    {0, 0, 0, 0, 0, 1, 0, 0},
+	    {1, 1, 0, 0, 0, 1, 1, 1},
+	    {2, 2, 0, 0, 0, 1, 2, 2},
+	    {-1, -2, 1, 0, 0, 1, 0, -2},
+	    {0, 1, 1, 0, 0, 1, 1, 0},
+	    {-1, 0, 0, 0, 0, 1, 1, 0},
+	};
+
+	const unsigned int indices[] = {
+	    0, 3, 1, // outer, positive
+	    0, 1, 2, // inner, degenerate UVs
+	    1, 4, 2, // outer, positive
+	    2, 5, 0, // outer, negative
+	};
+
+	float tangents[12 * 4];
+	meshopt_generateTangents(tangents, indices, 12, &vertices[0].px, 6, sizeof(Vertex), &vertices[0].nx, sizeof(Vertex), &vertices[0].tx, sizeof(Vertex), meshopt_TangentCompatible);
+
+	const float vx = 0.0836f;
+	const float vy = 0.9965f;
+	const float expected[12][4] = {
+	    // outer, positive
+	    {1.f, 0.f, 0.f, 1.f}, // 0
+	    {1.f, 0.f, 0.f, 1.f}, // 3
+	    {vx, vy, 0.f, 1.f},   // 1
+	    // inner, degenerate UVs
+	    {1.f, 0.f, 0.f, 1.f}, // 0
+	    {vx, vy, 0.f, 1.f},   // 1
+	    {0.f, 1.f, 0.f, 1.f}, // 2
+	    // outer, positive
+	    {vx, vy, 0.f, 1.f},   // 1
+	    {0.f, 1.f, 0.f, 1.f}, // 4
+	    {0.f, 1.f, 0.f, 1.f}, // 2
+	    // outer, negative
+	    {-1.f, 0.f, 0.f, -1.f}, // 2 (split)
+	    {-1.f, 0.f, 0.f, -1.f}, // 5
+	    {-1.f, 0.f, 0.f, -1.f}, // 0 (split)
+	};
+
+	for (size_t i = 0; i < 12; ++i)
+		for (size_t k = 0; k < 4; ++k)
+			assert(fabsf(tangents[i * 4 + k] - expected[i][k]) < 1e-3f);
+}
+
 void runTests()
 {
 	decodeIndexV0();
@@ -3254,4 +3308,6 @@ void runTests()
 	opacityMap();
 	opacityMapRasterize0();
 	opacityMapSpecial();
+
+	tangentDegenerate();
 }

src/meshoptimizer.h

@@ -898,9 +898,20 @@ MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapEntrySize(int level, int sta
  */
 MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapCompact(unsigned char* data, size_t data_size, unsigned char* levels, unsigned int* offsets, size_t omm_count, int* omm_indices, size_t triangle_count, int states);
 
+/**
+ * Tangent generation options
+ */
+enum
+{
+	/* Produce tangents compatible with MikkTSpace (same weighting and fallbacks) at the cost of reduced quality. Not recommended unless normal maps are baked. */
+	meshopt_TangentCompatible = 1 << 0,
+	/* Experimental: For vertices only connected to degenerate triangles, output zero tangents instead of an arbitrary fallback.  */
+	meshopt_TangentZeroFallback = 1 << 1,
+};
+
 /**
  * Experimental: Tangent space generator
- * Computes per-corner tangent vectors following the MikkTSpace algorithm; for each corner, computes normalized tangent vector (xyz) and orientation (w, +/-1).
+ * Computes per-corner tangent vectors; for each corner, computes normalized tangent vector (xyz) and orientation (w, +/-1).
  * Bitangent can be reconstructed via cross(normal, tangent.xyz) * tangent.w.
  * To apply tangents to the mesh, either deindex and reindex it with the tangent stream, or copy tangents to existing vertex data while duplicating
  * vertices with different tangent vectors (e.g. on UV mirror seams).
@@ -912,7 +923,7 @@ MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapCompact(unsigned char* data,
  * vertex_normals should have unit float3 normal in the first 12 bytes of each vertex
  * vertex_uvs should have float2 texture coordinate in the first 8 bytes of each vertex
  */
-MESHOPTIMIZER_EXPERIMENTAL void meshopt_generateTangents(float* result, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride);
+MESHOPTIMIZER_EXPERIMENTAL void meshopt_generateTangents(float* result, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options);
 
 /**
  * Quantize a float into half-precision (as defined by IEEE-754 fp16) floating point value
@@ -1055,7 +1066,7 @@ inline size_t meshopt_partitionClusters(unsigned int* destination, const T* clus
 template <typename T>
 inline void meshopt_spatialSortTriangles(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
 template <typename T>
-inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride);
+inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options = 0);
 #endif
 
 /* Inline implementation */
@@ -1548,11 +1559,11 @@ inline void meshopt_spatialSortTriangles(T* destination, const T* indices, size_
 }
 
 template <typename T>
-inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride)
+inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options)
 {
 	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
 
-	meshopt_generateTangents(result, indices ? in.data : NULL, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_normals, vertex_normals_stride, vertex_uvs, vertex_uvs_stride);
+	meshopt_generateTangents(result, indices ? in.data : NULL, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_normals, vertex_normals_stride, vertex_uvs, vertex_uvs_stride, options);
 }
 #endif