Automatic merge of T1.5.1-687-gd279e384a and 10 pull requests

- Pull request #570 at c59c788: 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 #865 at 67014b7: Dispatcher window improvements
- Pull request #874 at f8dbeab: Dynamic brake controller refactoring
- 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 #878 at da8978d: Implement Polach Adhesion
- Pull request #882 at e92ff49: Blueprint/train car operations UI window
- Pull request #883 at edcc2dd: SwitchPanel disconnect/connect handling
- Pull request #885 at c81447b: feat: Add notifications to Menu

Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs

@@ -3181,7 +3181,6 @@ public virtual void UpdateFrictionCoefficient(float elapsedClockSeconds)
 
         #endregion
 
-
         public void UpdateTrackSander(float elapsedClockSeconds)
         {
         // updates track sander in terms of sand usage and impact on air compressor

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

@@ -582,7 +582,7 @@ public float TransmissionEfficiency
         public float WheelSlipThresholdMpS;
         public void ComputeWheelSlipThresholdMpS()
         {
-            // Bisection algorithm. We assume adhesion maximum is between 0 and 4 m/s
+            // Bisection algorithm. We assume adhesion maximum is between 0 (0.005) and 4 m/s
             double a = 0.005f;
             double b = 4;
             // We have to find the zero of the derivative of adhesion curve
@@ -592,30 +592,7 @@ public void ComputeWheelSlipThresholdMpS()
             double fa = SlipCharacteristics(a + dx) - SlipCharacteristics(a);
             double fb = SlipCharacteristics(b + dx) - SlipCharacteristics(b);
 
-            double p = 0.025f;
-            double s = 0.05f;
-            double t = 0.1f;
-            double q = 0.15f;
-            double r = 0.2f;
-            double u = 0.25f;
-            double v = 0.5f;
-            double x = 0.75f;
-            double y = 1.0f;
-
-            double fa1 = SlipCharacteristics(a);
-            double fb1 = SlipCharacteristics(b);
-
-            double fp = SlipCharacteristics(p);
-            double fs = SlipCharacteristics(s);
-            double ft = SlipCharacteristics(t);
-            double fq = SlipCharacteristics(q);
-            double fr = SlipCharacteristics(r);
-            double fu = SlipCharacteristics(u);
-            double fv = SlipCharacteristics(v);
-            double fx = SlipCharacteristics(x);
-            double fy = SlipCharacteristics(y);
             double SlipSpeedMpS = AxleSpeedMpS - TrainSpeedMpS;
-            double fslip = SlipCharacteristics(SlipSpeedMpS);
 
             MaximumPolachWheelAdhesion = (float)SlipCharacteristics(WheelSlipThresholdMpS);
 
@@ -644,7 +621,6 @@ public void ComputeWheelSlipThresholdMpS()
                 else
                 {
                     b = c;
-                    fb = fc;
                 }
             }
             WheelSlipThresholdMpS = (float)Math.Max((a + b) / 2, MpS.FromKpH(0.1f));
@@ -724,7 +700,7 @@ public float SlipDerivationPercentpS
         }
 
         double integratorError;
-        int waitBeforeIntegreationRate;
+        int waitBeforeChangingRate;
 
         /// <summary>
         /// Read/Write relative slip speed warning threshold value, in percent of maximal effective slip
@@ -868,21 +844,23 @@ public void Save(BinaryWriter outf)
         /// <summary>
         /// Integrates the wheel rotation movement using a RK4 method,
         /// calculating the required number of substeps
+        /// To maintain the accuracy of the integration method, the number of substeps needs to increase when slip speed approaches the slip threshold speed.
+        /// The folloi=wing section attempts to calculate the optimal substep limit. This is a trade off between the accuracy of the slips calculations and the CPU load which impacts the screen FPS
         /// Outputs: wheel speed, wheel angular position and motive force
         /// </summary>
         void Integrate(float elapsedClockSeconds)
         {
             if (elapsedClockSeconds <= 0) return;
             double prevSpeedMpS = AxleSpeedMpS;
 
-            float upperSubStepStartingLimit = 120;
+            float upperSubStepStartingLimit = 100;
             float tempupperSubStepLimit = upperSubStepStartingLimit;
             float lowerSubStepLimit = 1;
 
             float screenFrameUpperLimit = 60;
             float screenFrameLowerLimit = 40;
 
-            // Reduces the number of substeps if screen FPS drops
+            // Reduces the number of substeps if screen FPS drops below a nominal rate of 60 fps
             if ( (int)ScreenFrameRate >= screenFrameUpperLimit) // Screen FPS > 60, hold substeps @ maximum value
             {
                 tempupperSubStepLimit = upperSubStepStartingLimit;
@@ -909,31 +887,44 @@ void Integrate(float elapsedClockSeconds)
                 targetNumOfSubstepsPS = upperSubStepLimit;
             }
 
-            if (Math.Abs(integratorError) < 0.000277 && !IsWheelSlip && !IsWheelSlipWarning && SlipSpeedMpS < 0.4 * WheelSlipThresholdMpS)
+            if (Math.Abs(integratorError) < 0.000277 && !IsWheelSlip && !IsWheelSlipWarning && SlipSpeedMpS < 0.25 * WheelSlipThresholdMpS && SlipSpeedMpS < previousSlipSpeedMpS)
             {
-                if (--waitBeforeIntegreationRate <= 0) //wait for a while before changing the integration rate
+                if (--waitBeforeChangingRate <= 0) //wait for a while before changing the integration rate
                 {
                     NumOfSubstepsPS -= 2; // decrease substeps when under low slip conditions
-                    waitBeforeIntegreationRate = 20;
+                    waitBeforeChangingRate = 30;
                 }
             }
             else if (targetNumOfSubstepsPS > NumOfSubstepsPS) // increase substeps
             {
-                if (--waitBeforeIntegreationRate <= 0 ) //wait for a while before changing the integration rate
+                if (--waitBeforeChangingRate <= 0 ) //wait for a while before changing the integration rate
                 {
-                    NumOfSubstepsPS += 5;
-                    waitBeforeIntegreationRate = 30;      //not so fast ;)
+
+                    if (IsWheelSlip || IsWheelSlipWarning || SlipSpeedMpS > previousSlipSpeedMpS)
+                    {
+                        // this speeds up the substep increase if the slip speed approaches the threshold or has exceeded it, ie "critical conditions".
+                        NumOfSubstepsPS += 10;
+                        waitBeforeChangingRate = 5;      
+                    }
+                    else
+                    {
+                        // this speeds ups the substeps under "non critical" conditions
+                        NumOfSubstepsPS += 3;
+                        waitBeforeChangingRate = 30;      
+                    }
+
                 }
             }
             else if (targetNumOfSubstepsPS < NumOfSubstepsPS) // decrease sub steps
             {
-                if (--waitBeforeIntegreationRate <= 0) //wait for a while before changing the integration rate
+                if (--waitBeforeChangingRate <= 0) //wait for a while before changing the integration rate
                 {
-                    NumOfSubstepsPS -= 5;
-                    waitBeforeIntegreationRate = 20;
+                    NumOfSubstepsPS -= 3;
+                    waitBeforeChangingRate = 30;
                 }
             }
 
+            // keeps the substeps to a relevant upper and lower limits
             if (NumOfSubstepsPS < lowerSubStepLimit)
                 NumOfSubstepsPS = (int)lowerSubStepLimit;
 
@@ -1178,7 +1169,6 @@ public double SlipCharacteristics(double slipSpeedMpS)
             }
         }
 
-
         /// <summary>
         /// Uses the Polach creep force curves calculation described in the following document
         ///	"Creep forces in simulations of traction vehicles running on adhesion limit" by O. Polach 2005 Wear - http://www.sze.hu/~szenasy/VILLVONT/polachslipvizsg.pdf