Automatic merge of T1.5.1-770-g1f196a324 and 16 pull requests

- Pull request #570 at 3539862: Experimental glTF 2.0 support with PBR lighting
- Pull request #839 at d00beb9: First phase of https://blueprints.launchpad.net/or/+spec/additional-cruise-control-parameters
- Pull request #875 at 43bf33e: Bug fix for https://bugs.launchpad.net/or/+bug/2036346 Player train switching doesn't work with 3D cabs
- Pull request #876 at f92de76: docs: add source for documents previously on website to source Documentation folder
- Pull request #882 at a055bca: Blueprint/train car operations UI window
- Pull request #885 at d9ce84b: feat: Add notifications to Menu
- Pull request #886 at 6c0785b: Scene viewer extension to TrackViewer
- Pull request #892 at 1f5ba4c: Signal Function OPP_SIG_ID_TRAINPATH
- Pull request #893 at bf8876b: Signal errors
- Pull request #894 at 5ff1e73: Correct Decrease Colour
- Pull request #896 at 5866028: First implementation of https://blueprints.launchpad.net/or/+spec/specific-sounds-for-ai-trains
- Pull request #897 at 0a9d939: feat: Improved system information collection
- Pull request #898 at 2d1b44a: Extra line with all the arguments for debugging purposes in logfile
- Pull request #899 at c17fdb3: Duplex steam engines - Booster Engine addition
- Pull request #903 at a0d2991: first phase downloading from Github
- Pull request #904 at 8dc3628: fix: adds downgrade to low precision

Author: openrails-bot

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/PowerTransmissions/Axle.cs

@@ -29,6 +29,8 @@
 using Orts.Simulation.RollingStocks.SubSystems.PowerTransmissions;
 using SharpDX.Direct2D1;
 using SharpDX.Direct3D9;
+using Orts.Formats.OR;
+using static Orts.Simulation.RollingStocks.SubSystems.PowerTransmissions.Axle;
 
 namespace Orts.Simulation.RollingStocks.SubSystems.PowerTransmissions
 {
@@ -1017,37 +1019,13 @@ void Integrate(float elapsedClockSeconds)
         /// - computes axle dynamic model according to its driveType
         /// - computes wheelslip indicators
         /// </summary>
-        /// <param name="timeSpan"></param>
-        public virtual void Update(float timeSpan)
+        /// <param name="elapsedSeconds"></param>
+        public virtual void Update(float elapsedSeconds)
         {
-            // Test to determine whether to use Polach or Pacha adhesion
-                        
-            // Switches between Polach (high performance) adhesion model and Pacha (low performance) adhesion model depending upon the PC performance
-            if(timeSpan < 0.025) // timespan 0.025 = 40 fps screen rate, low timeSpan and high FPS
-            {
-                UsePolachAdhesion = true;
-            }
-            else if(timeSpan > 0.033) // timespan 0.033 = 30 fps screen rate, high timeSpan and low FPS
-            {
-                UsePolachAdhesion = false;
-                if (TrainSpeedMpS > 0 )
-                {
-                    var ScreenFrameRate = 1 / timeSpan;
-                    Trace.TraceInformation("Advanced adhesion model switched to low performance option due to low frame rate {0} at ElapsedClockSeconds of {1}", ScreenFrameRate, timeSpan);
-
-                }
-
-                // Set values for Pacha adhesion
-                WheelSlipThresholdMpS = MpS.FromKpH(AdhesionK / AdhesionLimit);
-                WheelAdhesion = 0.99f;
-                MaximumPolachWheelAdhesion = 0.99f;
-
-            }
-            
-            forceToAccelerationFactor = WheelRadiusM * WheelRadiusM / totalInertiaKgm2;        
-
+            UsePolachAdhesion = AdhesionPrecision.IsPrecisionHigh(elapsedSeconds);
             if (UsePolachAdhesion)
             {
+                forceToAccelerationFactor = WheelRadiusM * WheelRadiusM / totalInertiaKgm2;
 
                 Polach.Update();
                 axleStaticForceN = AxleWeightN * SlipCharacteristicsPolach(0);
@@ -1060,6 +1038,15 @@ public virtual void Update(float timeSpan)
                     axleStaticForceN = AxleWeightN * SlipCharacteristicsPolach(0);
                 }
             }
+            else
+            {
+                // Set values for Pacha adhesion
+                WheelSlipThresholdMpS = MpS.FromKpH(AdhesionK / AdhesionLimit);
+                WheelAdhesion = 0.99f;
+                MaximumPolachWheelAdhesion = 0.99f;
+
+                forceToAccelerationFactor = WheelRadiusM * WheelRadiusM / totalInertiaKgm2;
+            }
 
 #if DEBUG_ADHESION
             double[] spd = new double[50];
@@ -1084,9 +1071,9 @@ public virtual void Update(float timeSpan)
             Console.WriteLine("");
 #endif
 
-            motor?.Update(timeSpan);
+            motor?.Update(elapsedSeconds);
 
-            Integrate(timeSpan);
+            Integrate(elapsedSeconds);
             // TODO: We should calculate brake force here
             // Adding and substracting the brake force is correct for normal operation,
             // but during wheelslip this will produce wrong results.
@@ -1114,14 +1101,14 @@ public virtual void Update(float timeSpan)
                 {
                     IsWheelSlip = IsWheelSlipWarning = true;
                 }
-                WheelSlipTimeS += timeSpan;
+                WheelSlipTimeS += elapsedSeconds;
             }
             else if (Math.Abs(SlipSpeedPercent) > SlipWarningTresholdPercent)
             {
                 // Wait some time before indicating wheelslip to avoid false triggers
                 if (WheelSlipWarningTimeS > 1) IsWheelSlipWarning = true;
                 IsWheelSlip = false;
-                WheelSlipWarningTimeS += timeSpan;
+                WheelSlipWarningTimeS += elapsedSeconds;
             }
             else
             {
@@ -1130,16 +1117,62 @@ public virtual void Update(float timeSpan)
                 WheelSlipWarningTimeS = WheelSlipTimeS = 0;
             }
 
-            if (timeSpan > 0.0f)
+            if (elapsedSeconds > 0.0f)
             {
-                slipDerivationMpSS = (SlipSpeedMpS - previousSlipSpeedMpS) / timeSpan;
+                slipDerivationMpSS = (SlipSpeedMpS - previousSlipSpeedMpS) / elapsedSeconds;
                 previousSlipSpeedMpS = SlipSpeedMpS;
 
-                slipDerivationPercentpS = (SlipSpeedPercent - previousSlipPercent) / timeSpan;
+                slipDerivationPercentpS = (SlipSpeedPercent - previousSlipPercent) / elapsedSeconds;
                 previousSlipPercent = SlipSpeedPercent;
             }
         }
 
+        static class AdhesionPrecision  // "static" so all "Axle"s share the same level of precision
+        {
+            enum AdhesionPrecisionLevel
+            {
+                /// <summary>
+                /// Initial level uses Polach algorithm
+                /// </summary>
+                High,
+                /// <summary>
+                /// Low-performance PCs use Pacha's algorithm
+                /// </summary>
+                Low
+            }
+
+            static AdhesionPrecisionLevel PrecisionLevel = AdhesionPrecisionLevel.High;
+            static double TimeOfLatestDowngrade = 0;
+
+            // Adjustable limits
+            const float UpperLimitS = 0.033f;   // timespan 0.033 = 30 fps screen rate, high timeSpan and low FPS
+
+            // Tested by varying the framerate interactively. Did this by opening and closing the HelpWindow after inserting
+            //   Threading.Thread.Sleep(40);
+            // into HelpWindow.PrepareFrame() temporarily.
+            public static bool IsPrecisionHigh(float elapsedSeconds)
+            {
+                // Switches between Polach (high precision) adhesion model and Pacha (low precision) adhesion model depending upon the PC performance
+                switch (PrecisionLevel)
+                {
+                    case AdhesionPrecisionLevel.High:
+                        if (elapsedSeconds > UpperLimitS)
+                        {
+                            var screenFrameRate = 1 / elapsedSeconds;
+                            {
+                                Trace.TraceInformation($"Advanced adhesion model switched to low precision permanently after low frame rate {screenFrameRate:F1} below limit {1 / UpperLimitS:F0}");
+                                PrecisionLevel = AdhesionPrecisionLevel.Low;
+                            }
+                        }
+                        break;
+
+                    case AdhesionPrecisionLevel.Low:
+                        break;
+                }
+                return (PrecisionLevel == AdhesionPrecisionLevel.High);
+            }
+        }
+
         class PolachCalculator
         {
             Axle Axle;
@@ -1230,6 +1263,7 @@ public void Update()
                 polach_Ks = (1.2 * zeroSpeedAdhesion) - 0.26;
                 if (polach_Ks < 0.1) polach_Ks = 0.1f;
             }
+
             public double SlipCharacteristics(double slipSpeedMpS)
             {
                 var polach_uadhesion = zeroSpeedAdhesion * (((1 - polach_A) * Math.Exp(-polach_B * slipSpeedMpS)) + polach_A);