mikktspace.h
1 
24 #ifndef __MIKKTSPACE_H__
25 #define __MIKKTSPACE_H__
26 
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /* Author: Morten S. Mikkelsen
33  * Version: 1.0
34  *
35  * The files mikktspace.h and mikktspace.c are designed to be
36  * stand-alone files and it is important that they are kept this way.
37  * Not having dependencies on structures/classes/libraries specific
38  * to the program, in which they are used, allows them to be copied
39  * and used as is into any tool, program or plugin.
40  * The code is designed to consistently generate the same
41  * tangent spaces, for a given mesh, in any tool in which it is used.
42  * This is done by performing an internal welding step and subsequently an order-independent evaluation
43  * of tangent space for meshes consisting of triangles and quads.
44  * This means faces can be received in any order and the same is true for
45  * the order of vertices of each face. The generated result will not be affected
46  * by such reordering. Additionally, whether degenerate (vertices or texture coordinates)
47  * primitives are present or not will not affect the generated results either.
48  * Once tangent space calculation is done the vertices of degenerate primitives will simply
49  * inherit tangent space from neighboring non degenerate primitives.
50  * The analysis behind this implementation can be found in my master's thesis
51  * which is available for download --> http://image.diku.dk/projects/media/morten.mikkelsen.08.pdf
52  * Note that though the tangent spaces at the vertices are generated in an order-independent way,
53  * by this implementation, the interpolated tangent space is still affected by which diagonal is
54  * chosen to split each quad. A sensible solution is to have your tools pipeline always
55  * split quads by the shortest diagonal. This choice is order-independent and works with mirroring.
56  * If these have the same length then compare the diagonals defined by the texture coordinates.
57  * XNormal which is a tool for baking normal maps allows you to write your own tangent space plugin
58  * and also quad triangulator plugin.
59  */
60 
61 
62 typedef int tbool;
64 
65 typedef struct {
66  // Returns the number of faces (triangles/quads) on the mesh to be processed.
67  int (*m_getNumFaces)(const SMikkTSpaceContext * pContext);
68 
69  // Returns the number of vertices on face number iFace
70  // iFace is a number in the range {0, 1, ..., getNumFaces()-1}
71  int (*m_getNumVerticesOfFace)(const SMikkTSpaceContext * pContext, const int iFace);
72 
73  // returns the position/normal/texcoord of the referenced face of vertex number iVert.
74  // iVert is in the range {0,1,2} for triangles and {0,1,2,3} for quads.
75  void (*m_getPosition)(const SMikkTSpaceContext * pContext, float fvPosOut[], const int iFace, const int iVert);
76  void (*m_getNormal)(const SMikkTSpaceContext * pContext, float fvNormOut[], const int iFace, const int iVert);
77  void (*m_getTexCoord)(const SMikkTSpaceContext * pContext, float fvTexcOut[], const int iFace, const int iVert);
78 
79  // either (or both) of the two setTSpace callbacks can be set.
80  // The call-back m_setTSpaceBasic() is sufficient for basic normal mapping.
81 
82  // This function is used to return the tangent and fSign to the application.
83  // fvTangent is a unit length vector.
84  // For normal maps it is sufficient to use the following simplified version of the bitangent which is generated at pixel/vertex level.
85  // bitangent = fSign * cross(vN, tangent);
86  // Note that the results are returned unindexed. It is possible to generate a new index list
87  // But averaging/overwriting tangent spaces by using an already existing index list WILL produce INCRORRECT results.
88  // DO NOT! use an already existing index list.
89  void (*m_setTSpaceBasic)(const SMikkTSpaceContext * pContext, const float fvTangent[], const float fSign, const int iFace, const int iVert);
90 
91  // This function is used to return tangent space results to the application.
92  // fvTangent and fvBiTangent are unit length vectors and fMagS and fMagT are their
93  // true magnitudes which can be used for relief mapping effects.
94  // fvBiTangent is the "real" bitangent and thus may not be perpendicular to fvTangent.
95  // However, both are perpendicular to the vertex normal.
96  // For normal maps it is sufficient to use the following simplified version of the bitangent which is generated at pixel/vertex level.
97  // fSign = bIsOrientationPreserving ? 1.0f : (-1.0f);
98  // bitangent = fSign * cross(vN, tangent);
99  // Note that the results are returned unindexed. It is possible to generate a new index list
100  // But averaging/overwriting tangent spaces by using an already existing index list WILL produce INCRORRECT results.
101  // DO NOT! use an already existing index list.
102  void (*m_setTSpace)(const SMikkTSpaceContext * pContext, const float fvTangent[], const float fvBiTangent[], const float fMagS, const float fMagT,
103  const tbool bIsOrientationPreserving, const int iFace, const int iVert);
105 
107 {
108  SMikkTSpaceInterface * m_pInterface; // initialized with callback functions
109  void * m_pUserData; // pointer to client side mesh data etc. (passed as the first parameter with every interface call)
110 };
111 
112 // these are both thread safe!
113 tbool genTangSpaceDefault(const SMikkTSpaceContext * pContext); // Default (recommended) fAngularThreshold is 180 degrees (which means threshold disabled)
114 tbool genTangSpace(const SMikkTSpaceContext * pContext, const float fAngularThreshold);
115 
116 
117 // To avoid visual errors (distortions/unwanted hard edges in lighting), when using sampled normal maps, the
118 // normal map sampler must use the exact inverse of the pixel shader transformation.
119 // The most efficient transformation we can possibly do in the pixel shader is
120 // achieved by using, directly, the "unnormalized" interpolated tangent, bitangent and vertex normal: vT, vB and vN.
121 // pixel shader (fast transform out)
122 // vNout = normalize( vNt.x * vT + vNt.y * vB + vNt.z * vN );
123 // where vNt is the tangent space normal. The normal map sampler must likewise use the
124 // interpolated and "unnormalized" tangent, bitangent and vertex normal to be compliant with the pixel shader.
125 // sampler does (exact inverse of pixel shader):
126 // float3 row0 = cross(vB, vN);
127 // float3 row1 = cross(vN, vT);
128 // float3 row2 = cross(vT, vB);
129 // float fSign = dot(vT, row0)<0 ? -1 : 1;
130 // vNt = normalize( fSign * float3(dot(vNout,row0), dot(vNout,row1), dot(vNout,row2)) );
131 // where vNout is the sampled normal in some chosen 3D space.
132 //
133 // Should you choose to reconstruct the bitangent in the pixel shader instead
134 // of the vertex shader, as explained earlier, then be sure to do this in the normal map sampler also.
135 // Finally, beware of quad triangulations. If the normal map sampler doesn't use the same triangulation of
136 // quads as your renderer then problems will occur since the interpolated tangent spaces will differ
137 // eventhough the vertex level tangent spaces match. This can be solved either by triangulating before
138 // sampling/exporting or by using the order-independent choice of diagonal for splitting quads suggested earlier.
139 // However, this must be used both by the sampler and your tools/rendering pipeline.
140 
141 #ifdef __cplusplus
142 }
143 #endif
144 
145 #endif
Definition: mikktspace.h:65
Definition: mikktspace.h:106