Automatic merge of T1.6-89-ga2a9bbcc8 and 11 pull requests

- Pull request #1156 at f46d5f2: Fix incorrectly disabled options in train operations window
- Pull request #1086 at d8d61eb: Add Settings Exporter tool (copy settings to INI, etc)
- Pull request #1091 at e813c42: Automatic speed control
- Pull request #1115 at 270f22f: Do not activate ETS switch if no suitable cars are attached
- Pull request #1120 at ba3c47f: Automatically Calculate Friction Values if Missing
- Pull request #1121 at 91d2d26: Manually Override Articulation
- Pull request #1124 at e241a0d: Built-in PBL2 brake controller
- Pull request #1126 at 95e884f: ShapeHierarchy Attachment for More Wagon Addons
- Pull request #1157 at 39cd994: Dynamic brake authorization by TCS
- Pull request #1159 at 48c9a63: Skip OR warnings about TSRE-specific token Ruler
- Pull request #1082 at 5845a1a: Allow variable water level in glass gauge

Author: openrails-bot

Source/Documentation/Manual/cabs.rst

@@ -1234,6 +1234,53 @@ in the .cvf header, that is the right side viewpoint.
 
 Note that in Open Rails you may have more than three cabviewpoints defined for 2D cabs.
 
+Advanced cab viewport positioning
+---------------------------------
+
+.. index::
+   single: ORTSShapeHierarchy
+
+In some unusual cases, it may be desired to have the cab view point move not with the main
+locomotive body, but with a sub object of the locomotive, such as a bogie. To do this, the
+parameter ``ORTSShapeHierarchy ( MATRIXNAME )`` can be added inside the .cvf file, once
+for each viewport. If this is used, the position of the viewport will no longer be measured
+relative to the locomotive itself, but relative to the sub object with the given name. As
+the sub object translates and rotates, the cab view will do the same in sync. Each viewport
+can be attached to a different sub object, though in many cases attaching all three to the
+same sub object will make the most sense::
+
+    Comment ( A hypothetical cab view where the cab is attached to the BOGIE1 sub object of the locomotive shape. )
+    Tr_CabViewFile (
+	    CabViewType ( 3 )
+	    CabViewFile ( Front.ace )
+	    CabViewWindow ( 0 0 640 400 )
+	    CabViewWindowFile ( "" )
+	    Position ( 1.265 3.44 6.24 )
+	    Direction ( 7 -20 1 )
+	    ORTSShapeHierarchy ( BOGIE1 )
+	    CabViewFile ( Rear.ace )
+	    CabViewWindow ( 0 0 640 480 )
+	    CabViewWindowFile ( "" )
+	    Position ( 1.26 3.44 6.24 )
+	    Direction ( 6 179 0 )
+	    ORTSShapeHierarchy ( BOGIE1 )
+	    CabViewFile ( Right.ace )
+	    CabViewWindow ( 0 0 640 480 )
+	    CabViewWindowFile ( "" )
+	    Position ( 1.26 3.44 6.24 )
+	    Direction ( 12 36 0 )
+	    ORTSShapeHierarchy ( BOGIE1 )
+
+Matrix names can be determined using shape viewing utilities. If the named matrix can't
+be found in the locomotive shape, a warning will be added to the log and the cab viewport
+will attach to the main shape object. ``ORTSShapeHierarchy`` is entirely optional, and if
+missing the cab viewport will be attached to the main shape object, same as in MSTS.
+
+Note that passenger views and 3D cabs also support ``ORTSShapeHierarchy`` but the
+:ref:`implementation is different<features-viewpoint-positioning>`, as it is not done
+inside the .cvf file.
+
+
 3D cabs
 =======
 
@@ -1283,40 +1330,48 @@ Development Rules
 - Within the Wagon section of the .eng file a block like the following one 
   has to be generated::
   
-    ORTS3DCab(
+    ORTS3DCab (
         ORTS3DCabFile ( Cab.s )
         ORTS3DCabHeadPos ( -0.9 2.4 5.2 )
         RotationLimit ( 40 60 0 )
         StartDirection ( 12 0 0 )
+        ORTSShapeOffset ( 0 0 0 )
+        ORTSShapeHierarchy ( MAIN )
     )
 
 - If also a rear cab is present, a second ``ORTS3DCab`` has to be added, 
   as follows::
 
-     ORTS3DCab(
+    ORTS3DCab (
         ORTS3DCabFile ( Cab.s )
         ORTS3DCabHeadPos ( 0.9 2.4 5.2 )
         RotationLimit ( 40 60 0 )
         StartDirection ( 12 180 0 )
+        ORTSShapeOffset ( 0 0 0 )
+        ORTSShapeHierarchy ( MAIN )
     )
 
+- Similarly to :ref:`passenger views<features-viewpoint-positioning>`,
+  ``ORTSShapeOffset`` and ``ORTSShapeHierarchy`` are optional and
+  give more control over the location of the cab shape and camera
+  location, but aren't needed for standard rolling stock.
+
 - Alternate 3D cab viewpoints may be added, as in the example here below::
 
-      ORTSAlternate3DCabViewPoints
-                         (
-        ORTSAlternate3DCabViewPoint(
-           ORTS3DCabFile ( Cab.s )
-           ORTS3DCabHeadPos ( 0.9 2.4 5.2 )
-           RotationLimit ( 40 60 0 )
-           StartDirection ( 12 0 0 )
-                        )
-        ORTSAlternate3DCabViewPoint(
-          ORTS3DCabFile ( Cab.s )
-          ORTS3DCabHeadPos ( -0.8 2.4 5.2 )
-          RotationLimit ( 40 60 0 )
-          StartDirection ( 12 30 0 )
-                        )
-                        )
+    ORTSAlternate3DCabViewPoints (
+        ORTSAlternate3DCabViewPoint (
+            ORTS3DCabFile ( Cab.s )
+            ORTS3DCabHeadPos ( 0.9 2.4 5.2 )
+            RotationLimit ( 40 60 0 )
+            StartDirection ( 12 0 0 )
+        )
+        ORTSAlternate3DCabViewPoint (
+            ORTS3DCabFile ( Cab.s )
+            ORTS3DCabHeadPos ( -0.8 2.4 5.2 )
+            RotationLimit ( 40 60 0 )
+            StartDirection ( 12 30 0 )
+        )
+    )
 
 
 -  To switch between alternate cab viewpoints ``Ctrl-Shift-1`` must be pressed.