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