Normal Types Page

docs/modules/core/pages/material/normal-types.adoc

@@ -0,0 +1,56 @@
+# Normal Map Conventions
+
+There are two conventions for normal maps:
+
+* OpenGL (known as OpenGL-Style)
+* DirectX (known as DirectX-Style)
+
+The difference between OpenGL style and DirectX style is the Y value (green channel) is flipped, so OpenGL uses Y+ and DirectX is Y-.
+This can cause shading to not look quite right if a shader tries to use OpenGL convention on a normal map designed for DirectX.
+
+Luckily, JME supports both OpenGL and DirectX conventions by using a `NormalType` parameter in the Lighting and PBRLighting material
+definitions. The parameter can be set to either 1 (to use OpenGL) or -1 (to use DirectX).
+By default, JME uses the DirectX convention (NormalType is -1).
+
+### Using NormalType
+
+If you're using Lighting.j3md or PBRLighting.j3md for your materials, you can use the NormalType parameter to set
+which normal map convention your normal maps are using.
+
+```java
+Material mat = new Material(assetManager,
+        "Common/MatDefs/Light/Lighting.j3md");
+mat.setInt("NormalType", 1); //set the type to OpenGL
+```
+
+### Which Convention are My Normal Maps?
+
+If you know what software created your normal map, then you can tell which convention the map uses. Here are the default
+conventions of some common 3D programs:
+
+[cols="2"]
+|===
+<a| Software
+<a| Convention
+a| Blender
+a| OpenGL
+a| Maya
+a| OpenGL
+a| 3ds Max
+a| DirectX
+a| JMonkeyEngine
+a| DirectX
+a| Unity3D
+a| OpenGL
+a| Unreal Engine
+a| DirectX
+
+|===
+
+If your normal map was created by Blender, then it will conform to the OpenGL convention. On the other hand, if it was
+created by 3ds Max, the normal map conforms to the DirectX convention.
+
+### Troubleshooting Normal Maps
+
+If the shading on your models seems a little wrong when lit, that's a good indicator that you're using the wrong
+normal map convention. Changing the NormalType on your materials should fix it (if it does not, there is something else wrong).