Introduce engine-agnostic normalFormat material stage keyword.

There is already a normalScale keyword which allows to revert channel by using a negative value, but this is not a way to describe the format of the file that is loaded. So, people would have to use a negative normalScale Y value in their .shader file if the normal map file is stored in DirectX way and the engine is computing normal maps the OpenGL way, but a positive Y normalScale value if file format and engine format matches.

By introducing the normalFormat stage keyword, artist can describe the normal map file format and don't mind about what the engine does. It also means the engine may switch its internal format without having to mind anything, the coder implementing another normal format would know how to convert the normal map file in engine whatever the format, not requiring him to ask artists to edit every existing .shader material file.

It was possible to make normalScale keyword engine-agnostic but that would be a very bad idea because this keyword exist in other engine of this lineage (idtech3 renderer2, OpenJK…, etc.). Then it's better to keep this keyword behaviour the way it works the same as other engine does.

For making things easier to think of, the engine is currently assuming a default normal map format is OpenGL (+X +Y +Z), because it's easier to multiply every channel with 1.0 by default whatever the channel when there is nothing to do.

For backward-compatibility purposes and to keep compatibility with other engines (idtech3 renderer2, XreaL, ET:Legacy, OpenJK, etc.), the normalMap, normalHeightMap keywords and bumpMap deprecated alias set the normal map format to DirectX one. Historically, the Doom 3 engine is an OpenGL engine using DirectX normal map format convention, and XreaL implemented normal maps in order to be able to load Doom3 formats, then expected DirectX normal maps. Engines like those I just quoted are reusing XreaL material stage keywords like normalMap that were Doom3 keywords at first, then are expecting DirectX format. It looks like we would have to live with it.

While the normalMap keyword is expecting normal map in the DirectX format because of backward compatibility with historical engines and third-party ones, Dæmon-based games developers are free to encourage the use of normal map using OpenGL format, maybe use contribution guidelines asking for normal map using OpenGL format explicitely. In such case contributors would just have to add the required line to tell the normal map is using OpenGL format.

The material stage keyword syntax is:

OpenGL format:

normalMap /textures/castle/brick_n
normalFormat X Y Z

DirectX format (normalFormat keyword is not required since nomalMap keyword already does it):

normalMap /textures/castle/brick_n
normalFormat X -Y Z

Weird format (like the one used in Vega texture set):

normalMap /textures/castle/brick_n
normalFormat -X -Y Z

With this work, we may one day change the normal map format used in GLSL code (see #274) without having to mind anything: the material parser is telling the engine which conversion to do, and the assets would not have to be edited if they use the normalFormat keyword.

The Vega map and texture set is expected to use the normalFormat keyword to fix normal map orientation in upcoming Unvanquished 0.52.

With such design we would be able to add support for alternative material syntax from other games to load normal maps, in such case, the keyword parsing code would just have to set the normal map format this syntax expects. The Darkplaces compatibility layer already does it this way.

Here are the default normal map formats used in engine:

• C++ engine: OpenGL
• XreaL normalMap keyword: DirectX
• Darkplaces _norm sidecar autoloading: OpenGL
• GLSL renderer as a black box: OpenGL
• GLSL code itself: DirectX (a hack reverts the Y channel on input, we may edit the code to avoid the Y reversion hack)