Add object hiding to .sd file and to freight animations

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -496,7 +496,7 @@ shape file and looking at the ``shader_names`` block near the top of the file. T
 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.
+transparency), and all are case-sensitive. 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
@@ -615,6 +615,56 @@ for them to appear in the intended locations. The location of a sub object is me
 so if the sub object parent is changed, it's position in the 3D world will change as well (unless corrected for,
 as was done here).
 
+Hiding Sub Objects
+''''''''''''''''''
+
+.. index::
+   single: ESD_ORTSObjectVisibility
+
+In some cases, it may be desired to simply disable rendering of some shape sub objects (for example,
+preventing low-poly objects from being rendered so they can be replaced with higher-poly freight
+animations). To achieve this, ``ESD_ORTSObjectVisibility'' may be added to to the Shape ( block of the
+shape descriptor file. ``ESD_ORTSObjectVisibility ( MATRIXNAME 0/1 )`` will take rendering of all
+sub objects controlled by the matrix called "MATRIXNAME" and make them visible if the second input is not 0,
+or invisible if the second input is 0. Note that 1 (the object is visible) is the default setting for all objects.
+If an object is set to be invisible, data for that object will not be sent to the GPU, saving render time,
+but any CPU calculations such as animations will still be applied to the sub object(s) and ``ORTSShapeHierarchy``
+can still be used to attach lights, freight animations, sounds, particles, etc to the object while invisible.
+Similarly, anything attached to a different matrix (regardless if that matrix is above or below the one made
+invisible) will remain visible and simulated unless specified otherwise.
+
+As an example, we can hide all the (low poly) wheels of an old locomotive in order to replace the wheels with
+(high poly) freight animations using the ORTSShapeHierarchy feature of :ref:`ORTS freight animations<orts-freight-anims>`::
+
+    SIMISA@@@@@@@@@@JINX0t1t______
+
+    shape ( SF_FP45_93.s
+        ESD_Detail_Level ( 0 )
+        ESD_Software_DLev ( 2 )
+        ESD_Alternative_Texture ( 0 )
+        ESD_Bounding_Box ( -1.632 -0.095 -10.99 1.684 4.628 10.99 )
+	
+        Comment ( Disable rendering, but not simulation, of all wheels. )
+        ESD_ORTSObjectVisibility (
+            WHEELS11 0
+            WHEELS12 0
+            WHEELS13 0
+            WHEELS21 0
+            WHEELS22 0
+            WHEELS23 0
+        )
+    )
+
+Note that, similar to other parameters, multiple objects can be hidden in one parameter by adding additional
+pairs of matrix names and 1/0 values. If a matrix name can't be found, the missing matrix will be skipped and
+a warning will be added to the log.
+
+This feature can also be used by freight animations directly using the ``ReplaceObject`` parameter; an ORTS freight
+animation with this parameter will disable rendering of the original object to which it is attached whenever the
+freight animation is visible. When used in combination with the ``ShapeHierarchy`` ORTS freight animation parameter,
+the freight animation can be used to effectively replace specific components of the original model without editing
+the .sd file. Users are encouraged to experiment with whichever approach works best.
+
 Transformation Matrix Name Changes
 ''''''''''''''''''''''''''''''''''
 
@@ -826,6 +876,8 @@ Other Vehicles:
 OR specific freight animations and pickups
 ------------------------------------------
 
+.. _orts-freight-anims:
+
 General
 '''''''
 
@@ -889,6 +941,7 @@ the first line of the include file must be blank.::
                 MaxHeight ( 0.3 )
                 MinHeight ( -2.0 )
                 FreightWeightWhenFull ( 99t )
+                ReplaceObject ( 0 )
                 FullAtStart ( 0 )
             )
             FreightAnimContinuous (
@@ -902,6 +955,7 @@ the first line of the include file must be blank.::
                 MaxHeight ( 0.3 )
                 MinHeight ( -2.0 )
                 FreightWeightWhenFull ( 99t )
+                ReplaceObject ( 0 )
                 FullAtStart ( 0 )
             )
         )
@@ -1009,6 +1063,12 @@ moment. The parameters of the subblock are described below:
 - ``FreightWeightWhenFull`` defines the mass of the freight when the wagon is full; 
   the mass of the wagon is computed by adding the mass of the empty wagon to the 
   actual mass of the freight 
+- ``ReplaceObject`` if set to 1 (ignored if missing) will disable rendering of the wagon
+  sub object to which the freightanim is attached. This works best when combined with
+  ``ShapeHierarchy`` to disable rendering of specific sub objects, effectively replacing
+  the sub object graphic with that of the freightanim. The intended use of this setting 
+  is to "delete" original shape parts and replace them with higher quality shapes without
+  editing the original shape.
 - ``FullAtStart`` defines wether the wagon is fully loaded ( 1 ) or is empty at game 
   start; if there are more continuous OR freightanims that have ``FullAtStart`` 
   set to 1, only the first one is considered.
@@ -1095,6 +1155,7 @@ freightanims. The ``FreightAnimStatic`` subblock has the following format::
             Flip ()
             ShapeHierarchy ( MATRIXNAME )
             Visibility ( "Outside, Cab2D, Cab3D" )
+            ReplaceObject ()
         )
     )
 

Source/Orts.Formats.Msts/ShapeDescriptorFile.cs

@@ -103,6 +103,18 @@ public SDShape(STFReader stf)
                     new STFReader.TokenProcessor("esd_ortsmatrixtranslation", ()=>{ ParseMatrixOverride(STFReader.UNITS.Distance, stf, ref ESD_MatrixTranslation); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixscale", ()=>{ ParseMatrixOverride(STFReader.UNITS.None, stf, ref ESD_MatrixScale); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixrotation", ()=>{ ParseMatrixOverride(STFReader.UNITS.Angle, stf, ref ESD_MatrixRotation); }),
+                    new STFReader.TokenProcessor("esd_ortsobjectvisibility", ()=>{
+                        stf.MustMatch("(");
+                        // Allow for multiple pairs of replaced and replacement values
+                        while (!stf.EndOfBlock())
+                        {
+                            string matName = stf.ReadString();
+                            bool setting = stf.ReadInt(1) != 0;
+                            // Add pair of values so long as we haven't reached the end of block
+                            if (!string.IsNullOrEmpty(matName) && !ESD_ObjectVisibility.ContainsKey(matName))
+                                ESD_ObjectVisibility.Add(matName, setting);
+                        }
+                    }),
                     new STFReader.TokenProcessor("esd_ortslodoverride", ()=>{
                         stf.MustMatch("(");
                         // Allow for multiple pairs of replaced and replacement values
@@ -128,6 +140,8 @@ public SDShape(STFReader stf)
                     ESD_ModifiedMatrices.Add(mat);
                 foreach (string mat in ESD_MatrixRotation.Keys)
                     ESD_ModifiedMatrices.Add(mat);
+                foreach (string mat in ESD_ObjectVisibility.Keys)
+                    ESD_ModifiedMatrices.Add(mat);
             }
             public int ESD_Detail_Level;
             public int ESD_Alternative_Texture;
@@ -153,6 +167,8 @@ public SDShape(STFReader stf)
             public Dictionary<string, Vector3> ESD_MatrixScale = new Dictionary<string, Vector3>();
             // Dictionary of <matrix name, matrix rotation x/y/z vector>
             public Dictionary<string, Vector3> ESD_MatrixRotation = new Dictionary<string, Vector3>();
+            // Dictionary of <matrix name, true/false visibility>
+            public Dictionary<string, bool> ESD_ObjectVisibility = new Dictionary<string, bool>();
             // Dictionary of <LOD index, LOD distance>
             public Dictionary<int, float> ESD_LODOverride = new Dictionary<int, float>();
 

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/FreightAnimations.cs

@@ -988,8 +988,9 @@ public enum VisibleFrom
         }
         public bool Flipped = false;
         public bool[] Visibility = { true, false, false };
+        public bool ReplaceObject = false;
         public Vector3 Offset = new Vector3();
-        public int ShapeIndex = -1; // TODO: Allow user inputs to specify ShapeIndex as per lights
+        public int ShapeIndex = -1;
         public string ShapeHierarchy;
     }
 
@@ -1054,6 +1055,7 @@ public FreightAnimationContinuous(STFReader stf, MSTSWagon wagon)
                 new STFReader.TokenProcessor("flip", ()=>{ Flipped = stf.ReadBoolBlock(true);}),
                 new STFReader.TokenProcessor("shapeindex", ()=>{ ShapeIndex = stf.ReadIntBlock(null);}),
                 new STFReader.TokenProcessor("shapehierarchy", ()=>{ ShapeHierarchy = stf.ReadStringBlock(null);}),
+                new STFReader.TokenProcessor("replaceobject", ()=>{ ReplaceObject = stf.ReadBoolBlock(true);}),
                 new STFReader.TokenProcessor("visibility", ()=>{
                     for (int index = 0; index < 3; index++)
                         Visibility[index] = false;
@@ -1183,6 +1185,7 @@ public FreightAnimationStatic(STFReader stf)
             new STFReader.TokenProcessor("flip", ()=>{ Flipped = stf.ReadBoolBlock(true);}),
             new STFReader.TokenProcessor("shapeindex", ()=>{ ShapeIndex = stf.ReadIntBlock(null);}),
             new STFReader.TokenProcessor("shapehierarchy", ()=>{ ShapeHierarchy = stf.ReadStringBlock(null);}),
+            new STFReader.TokenProcessor("replaceobject", ()=>{ ReplaceObject = stf.ReadBoolBlock(true);}),
             new STFReader.TokenProcessor("visibility", ()=>{
                 for (int index = 0; index < 3; index++)
                     Visibility[index] = false;

Source/RunActivity/Viewer3D/Lights.cs

@@ -125,7 +125,7 @@ public LightViewer(Viewer viewer, TrainCar car, TrainCarViewer carViewer)
                     }
                     else
                     {
-                        if (light.ShapeHierarchy != null)
+                        if (!string.IsNullOrEmpty(light.ShapeHierarchy))
                         {
                             if ((CarViewer as MSTSWagonViewer).TrainCarShape.SharedShape.MatrixNames.Contains(light.ShapeHierarchy))
                             {

Source/RunActivity/Viewer3D/ParticleEmitter.cs

@@ -258,7 +258,7 @@ public ParticleEmitterPrimitive(Viewer viewer, ParticleEmitterData data, MSTSWag
             }
             else
             {
-                if (EmitterData.ShapeHierarchy != null)
+                if (!string.IsNullOrEmpty(EmitterData.ShapeHierarchy))
                 {
                     if (CarViewer.TrainCarShape.SharedShape.MatrixNames.Contains(EmitterData.ShapeHierarchy))
                     {

Source/RunActivity/Viewer3D/RollingStock/MSTSLocomotiveViewer.cs

@@ -1358,7 +1358,7 @@ public CabRenderer(Viewer viewer, MSTSLocomotiveViewer carViewer)
                     }
                     else
                     {
-                        if (view.ShapeHierarchy != null)
+                        if (!string.IsNullOrEmpty(view.ShapeHierarchy))
                         {
                             if (carViewer.TrainCarShape.SharedShape.MatrixNames.Contains(view.ShapeHierarchy))
                             {

Source/RunActivity/Viewer3D/RollingStock/MSTSWagonViewer.cs

@@ -448,7 +448,7 @@ from data in effect.Value
                 }
                 else
                 {
-                    if (view.ShapeHierarchy != null)
+                    if (!string.IsNullOrEmpty(view.ShapeHierarchy))
                     {
                         if (TrainCarShape.SharedShape.MatrixNames.Contains(view.ShapeHierarchy))
                         {
@@ -739,13 +739,24 @@ public override void PrepareFrame(RenderFrame frame, ElapsedTime elapsedTime)
 
             if (FreightAnimations != null)
             {
-                foreach (var freightAnim in FreightAnimations.Animations)
+                foreach (FreightAnimationViewer freightAnim in FreightAnimations.Animations)
                 {
                     if (freightAnim.FreightShape?.DontRender == false)
                     {
                         // Display ORTS freight animation shape if cargo is loaded and visibility settings allow it to show
+                        // Disable rendering of original shape part if applicable
+                        if (freightAnim.Animation.ReplaceObject && TrainCarShape.Visibility[freightAnim.Animation.ShapeIndex])
+                            TrainCarShape.Visibility[freightAnim.Animation.ShapeIndex] = false;
+
                         freightAnim.FreightShape.PrepareFrame(frame, elapsedTime);
                     }
+                    else
+                    {
+                        // Allow original shape parts to render if applicable
+                        if (freightAnim.Animation.ReplaceObject && !TrainCarShape.Visibility[freightAnim.Animation.ShapeIndex] &&
+                            TrainCarShape.SharedShape.Visibility[freightAnim.Animation.ShapeIndex])
+                            TrainCarShape.Visibility[freightAnim.Animation.ShapeIndex] = true;
+                    }
                 }
             }
 

Source/RunActivity/Viewer3D/RollingStock/SubSystems/FreightAnimationsViewer.cs

@@ -94,7 +94,7 @@ public FreightAnimationViewer(Viewer viewer, MSTSWagonViewer wagonViewer, string
             }
             else
             {
-                if (Animation.ShapeHierarchy != null)
+                if (!string.IsNullOrEmpty(Animation.ShapeHierarchy))
                 {
                     if (wagonViewer.TrainCarShape.SharedShape.MatrixNames.Contains(Animation.ShapeHierarchy))
                     {

Source/RunActivity/Viewer3D/Shapes.cs

@@ -293,7 +293,8 @@ public class PoseableShape : StaticShape
 
         public readonly int[] Hierarchy;
 
-        public bool DontRender; // Flag to be used by other processes to see if the shape should not be rendered
+        public bool DontRender; // Flag to be used by other processes to see if the entire shape should not be rendered
+        public bool[] Visibility; // Specific flags to see if individual matrices should be rendered (0: don't render, 1: do render)
 
         public PoseableShape(Viewer viewer, string path, string descriptor, WorldPosition initialPosition, ShapeFlags flags)
             : base(viewer, path, descriptor, initialPosition, flags)
@@ -304,6 +305,7 @@ public PoseableShape(Viewer viewer, string path, string descriptor, WorldPositio
                 ResultMatrices = new Matrix[SharedShape.Matrices.Length];
                 for (int iMatrix = 0; iMatrix < SharedShape.Matrices.Length; ++iMatrix)
                     XNAMatrices[iMatrix] = SharedShape.Matrices[iMatrix];
+                Visibility = SharedShape.Visibility;
             }
             else // If the shape file is missing or fails to load, we need some default data to prevent crashes
             {
@@ -376,7 +378,7 @@ public void UpdateResultMatrices()
                     {
                         res = res * XNAMatrices[hIndex];
                         // Prevent potential infinite loop due to faulty hierarchy definition
-                        if (hIndex != Hierarchy[hIndex])
+                        if (hIndex != Hierarchy[hIndex] && hIndex != Hierarchy[i])
                             hIndex = Hierarchy[hIndex];
                         else
                             break;
@@ -392,7 +394,7 @@ public void UpdateResultMatrices()
 
         public override void PrepareFrame(RenderFrame frame, ElapsedTime elapsedTime)
         {
-            SharedShape.PrepareFrame(frame, Location, XNAMatrices, Flags);
+            SharedShape.PrepareFrame(frame, Location, XNAMatrices, Flags, Visibility);
         }
 
         public void ConditionallyPrepareFrame(RenderFrame frame, ElapsedTime elapsedTime, bool[] matrixVisible = null)
@@ -2057,6 +2059,7 @@ public class SharedShape : IDisposable
         public List<string> MatrixNames = new List<string>();
         public List<string> ImageNames; // Names of textures without paths or file extensions
         public Matrix[] Matrices = new Matrix[0];  // the original natural pose for this shape - shared by all instances
+        public bool[] Visibility = new bool[0]; // one flag per matrix to indicate if that matrix should be rendered
         public animations Animations;
         public LodControl[] LodControls;
         public bool HasNightSubObj;
@@ -2132,6 +2135,10 @@ void LoadContent()
 
 
             var textureFlags = Helpers.TextureFlags.None;
+            Visibility = new bool[sFile.shape.matrices.Count];
+            for (int vis = 0; vis < Visibility.Length; vis++)
+                Visibility[vis] = true; // Assume all matrices should be rendered by default
+
             ShapeDescriptorFile sdFile = null;
             bool adjustMAIN = false; // Check to see if the 0th matrix is modified in any way
             if (File.Exists(DescriptorPath))
@@ -2261,6 +2268,12 @@ void LoadContent()
                                 }
                             }
 
+                            // See if the objects associated with this shape should be hidden during rendering
+                            if (sdFile.shape.ESD_ObjectVisibility.TryGetValue(matName, out bool visible))
+                            {
+                                Visibility[i] = visible;
+                            }
+
                             found = true;
                         }
                     }

Source/RunActivity/Viewer3D/Sound.cs

@@ -757,7 +757,7 @@ public void Initialize(Viewer viewer, WorldLocation worldLocation, Events.Source
                         }
                         else
                         {
-                            if (mstsStream.ShapeHierarchy != null)
+                            if (!string.IsNullOrEmpty(mstsStream.ShapeHierarchy))
                             {
                                 if (CarViewer.TrainCarShape.SharedShape.MatrixNames.Contains(mstsStream.ShapeHierarchy))
                                 {