Add shader replacement to sd file

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -480,6 +480,44 @@ method to provide different textures for different engines/wagons as only one co
 needed, reducing install size and simplifying installation as users don't need to move/copy/edit any
 shape files.
 
+.. index::
+   single: ESD_ORTSShaderReplacement
+
+Shader Replacement
+''''''''''''''''''
+
+Similarly, it may be desired to replace the shaders used by a shape file in order to, for example, allow
+transparency to be applied to the shape and "alpha out" certain components. To change the shaders, add
+``ESD_ORTSShaderReplacement ( id ShaderName )`` where "id" is the integer index of the shader, starting from
+0, and "ShaderName" is the name of the new shader to use at this index. If an invalid shader index is given
+(eg: a negative number, or a number bigger than the max index), then a warning will be added to the log
+and the missing index will be skipped. Determining the order of shaders generally requires decompressing the
+shape file and looking at the ``shader_names`` block near the top of the file. The ``named_shader`` at the
+top of the list has an index of 0, the next one down has an index of 1, and so on. The accepted shader names are
+``Tex`` (fullbright), ``TexDiff`` (diffuse lighting), ``BlendATex`` (fullbright with transparency), ``BlendATextDiff``
+(diffuse with transparency), ``AddATex`` (fullbright with x-ray transparency), ``AddATexDiff`` (diffuse with x-ray
+transparency), if an invalid shader name is given a warning will be added to the log.
+
+For example, the US2BSignal2.s shape included with Marias Pass uses one shader, the ``TexDiff`` shader. This
+disallows transparency. If, for any reason, transparency were desired on this shape, the shape descriptor file
+could be edited as follows::
+
+    SIMISA@@@@@@@@@@JINX0t1t______
+
+    shape ( US2BSignal2.s
+        ESD_Detail_Level ( 0 )
+        ESD_Alternative_Texture ( 0 )
+
+        Comment ( Change the first, and only, shader to allow for transparency. )
+        ESD_ORTSShaderReplacement ( 0 "BlendATexDiff" )
+    )
+
+
+Like replacing textures, if multiple shaders are to be modified, all can be added in a single ``ESD_ORTSShaderReplacement``
+parameter by specifying additional pairs of indices and shader names. Note that changing shaders in this manner will
+change the shader for *all* sub objects linked to that shader. Changing the shader of an individual sub object from
+inside the .sd file is impractical, so an alternate method may be required if additional specificity is desired.
+
 Translation Matrix Modification
 '''''''''''''''''''''''''''''''
 

Source/Orts.Formats.Msts/ShapeDescriptorFile.cs

@@ -86,6 +86,18 @@ public SDShape(STFReader stf)
                     new STFReader.TokenProcessor("esd_ortsbellanimationfps", ()=>{ ESD_CustomAnimationFPS = stf.ReadFloatBlock(STFReader.UNITS.Frequency, null); }),
                     new STFReader.TokenProcessor("esd_ortscustomanimationfps", ()=>{ ESD_CustomAnimationFPS = stf.ReadFloatBlock(STFReader.UNITS.Frequency, null); }),
                     new STFReader.TokenProcessor("esd_ortstexturereplacement", ()=>{ ParseReplacementStrings(stf, ref ESD_TextureReplacement); }),
+                    new STFReader.TokenProcessor("esd_ortsshaderreplacement", ()=>{
+                        stf.MustMatch("(");
+                        // Allow for multiple pairs of replaced and replacement values
+                        while (!stf.EndOfBlock())
+                        {
+                            int replacedIdx = stf.ReadInt(-1);
+                            string replacement = stf.ReadString();
+                            // Add pair of values so long as we haven't reached the end of block
+                            if (!string.IsNullOrEmpty(replacement) && !ESD_ShaderReplacement.ContainsKey(replacedIdx))
+                                ESD_ShaderReplacement.Add(replacedIdx, replacement);
+                        }
+                    }),
                     new STFReader.TokenProcessor("esd_ortsmatrixrename", ()=>{ ParseReplacementStrings(stf, ref ESD_MatrixRename); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixparent", ()=>{ ParseReplacementStrings(stf, ref ESD_MatrixParent); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixtranslation", ()=>{ ParseMatrixOverride(STFReader.UNITS.Distance, stf, ref ESD_MatrixTranslation); }),
@@ -96,11 +108,11 @@ public SDShape(STFReader stf)
                         // Allow for multiple pairs of replaced and replacement values
                         while (!stf.EndOfBlock())
                         {
-                            int replaced = stf.ReadInt(null);
+                            int replacedIdx = stf.ReadInt(null);
                             float replacement = stf.ReadFloat(STFReader.UNITS.Distance, null);
                             // Add pair of values so long as we haven't reached the end of block
-                            if (replacement != 0)
-                                ESD_LODOverride.Add(replaced, replacement);
+                            if (replacement != 0 && !ESD_LODOverride.ContainsKey(replacedIdx))
+                                ESD_LODOverride.Add(replacedIdx, replacement);
                         }
                     }),
                 });
@@ -127,6 +139,8 @@ public SDShape(STFReader stf)
             public float ESD_CustomAnimationFPS = 8;
             // Dictionary of <original texture name, replacement texture name>
             public Dictionary<string, string> ESD_TextureReplacement = new Dictionary<string, string>();
+            // Dictionary of <shader index, shader name>
+            public Dictionary<int, string> ESD_ShaderReplacement = new Dictionary<int, string>();
             // Dictionary of <original matrix name, replacement matrix name>
             public Dictionary<string, string> ESD_MatrixRename = new Dictionary<string, string>();
             // Dictionary of <matrix name, new matrix parent name>
@@ -152,22 +166,23 @@ protected void ParseReplacementStrings(STFReader stf, ref Dictionary<string, str
                     string replaced = stf.ReadString();
                     string replacement = stf.ReadString();
                     // Add pair of values so long as we haven't reached the end of block
-                    if (replaced != ")" && replacement != ")")
+                    if (replaced != ")" && replacement != ")" && !renamePairs.ContainsKey(replaced))
                         renamePairs.Add(replaced, replacement);
                 }
             }
 
             // Handle matrix adjustment parameters
             protected void ParseMatrixOverride(STFReader.UNITS units, STFReader stf, ref Dictionary<string, Vector3> matrixParams)
             {
-                Vector3 data = new Vector3(0);
+                Vector3 data = Vector3.Zero;
 
                 stf.MustMatch("(");
                 string matName = stf.ReadString();
                 data = stf.ReadVector3(units, Vector3.Zero);
                 stf.SkipRestOfBlock();
 
-                matrixParams.Add(matName, data);
+                if (!matrixParams.ContainsKey(matName))
+                    matrixParams.Add(matName, data);
             }
         }
 

Source/RunActivity/Viewer3D/Shapes.cs

@@ -2145,8 +2145,8 @@ void LoadContent()
                 SoundFileName = sdFile.shape.ESD_SoundFileName;
                 CustomAnimationFPS = sdFile.shape.ESD_CustomAnimationFPS;
 
-                // Replace textures as defined in the sd file
-                foreach (string tex in sdFile.shape.ESD_TextureReplacement.Keys)
+                // Replace textures as defined in the .sd file
+                foreach (KeyValuePair<string, string> texSwap in sdFile.shape.ESD_TextureReplacement)
                 {
                     bool found = false;
 
@@ -2155,16 +2155,30 @@ void LoadContent()
                         // Check if shape uses one of the textures we want to replace
                         // Ignore case, ignore file extension
                         if (Path.GetFileNameWithoutExtension(sFile.shape.images[i].ToLower()) ==
-                            Path.GetFileNameWithoutExtension(tex.ToLower()))
+                            Path.GetFileNameWithoutExtension(texSwap.Key.ToLower()))
                         {
-                            sFile.shape.images[i] = sdFile.shape.ESD_TextureReplacement[tex];
+                            sFile.shape.images[i] = texSwap.Value;
                             found = true;
                         }    
                     }
 
                     if (!found)
                         Trace.TraceWarning("Shape descriptor file {0} specifies texture {1} to be replaced, " +
-                            "but shape {2} does not contain this texture.", DescriptorPath, tex, filePath);
+                            "but shape {2} does not contain this texture.", DescriptorPath, texSwap.Key, filePath);
+                }
+
+                // Replace shaders as defined in the .sd file
+                foreach (KeyValuePair<int, string> shaderSwap in sdFile.shape.ESD_ShaderReplacement)
+                {
+                    if (shaderSwap.Key >= 0 && shaderSwap.Key < sFile.shape.shader_names.Count)
+                    {
+                        sFile.shape.shader_names[shaderSwap.Key] = shaderSwap.Value;
+                    }
+                    else
+                    {
+                        Trace.TraceWarning("Shape descriptor file {0} specifies shader index {1} to be replaced, " +
+                            "but shape {2} does not have this many shaders.", DescriptorPath, shaderSwap.Key, filePath);
+                    }
                 }
 
                 int[] modifiedHierarchy = null;