Merge pull request #841 from Csantucci/animate-trainset-windows

https://blueprints.launchpad.net/or/+spec/animating-trainset-windows

Author: Csantucci

Source/Documentation/Manual/cabs.rst

@@ -819,6 +819,8 @@ and the mirrors.
 The control blocks are like the one shown for the cab light. The Type strings 
 are ORTS_LEFTDOOR, ORTS_RIGHTDOOR and ORTS_MIRRORS.
 
+Animation for 2D cab windows is described :ref:`here <features-windows>` .
+
 .. _cabs-generic-items:
 
 Cab controls for generic items
@@ -1025,6 +1027,7 @@ Rotation may be applied, with the same syntax, also to DigitalClock cab controls
 
 Display and animation of cabview controls in side views of 2D cabs
 ------------------------------------------------------------------
+.. _cabs-side-views:
 
 This is possible adding after the CabViewControls ( ) compound block an 
 ORTSCabviewControls ( ) compound block, that has the same format as the 
@@ -1211,6 +1214,7 @@ Development Rules
   font. If no ace is specified, the default will be used.
 - Mirrors and doors can be operated from 3D cabs. The names used are 
   ``LEFTDOOR``, ``RIGHTDOOR`` and ``MIRRORS``.
+- Animation for 3D cab windows is described :ref:`here <features-windows>` .  
 - like the 2D cabs, also 3D cabs can have a night version. Night textures, named like the 
   corresponding day textures, must be located within a ``NIGHT`` subfolder of the 
   ``CABVIEW3D`` folder. To enable night cabs an ``.sd`` file with the same name as the 

Source/Documentation/Manual/driving.rst

@@ -1091,10 +1091,24 @@ More information on connecting brakes and manipulating the brake hose
 connections can be found :ref:`here <physics-hud-brake>` and 
 :ref:`here <driving-car-operations>`.
 
-Doors and Mirror Commands
--------------------------
-
-Note that the standard keys in OR for these commands are different from 
+Doors, Mirror and Windows Commands
+----------------------------------
+.. _driving-anim-commands:
+
+Note that these commands are active only if the trainset is equipped with 
+the related animations.
+
+===================     =====================================
+Command                 Function
+===================     =====================================
+``<Q>``                 Door left open/close   
+``<Shift+Q>``           Door right open/close
+``<Shift+V>``           Mirror rotate clock/counterclockwise
+``<Ctrl+Q>``            Window left open/close
+``<Ctrl+Shift+Q>``      Window right open/close
+===================     =====================================
+
+Note that the standard keys for doors and mirror in OR are different from 
 those of MSTS.
 
 Wheelslip Reset

Source/Documentation/Manual/features-rollingstock.rst

@@ -1234,6 +1234,181 @@ ENG or WAG file::
   )
 
 
+.. _features-windows:
+
+Trainset windows
+================
+
+
+Left and right 2D- or 3D-cab windows can be animated, showing the animation both in cabview and in 
+external views. For locomotives also two windows for the rear cab can be defined.
+
+The external sounds and the track sound are reproduced unattenuated with open window. 
+To have a volume difference, two lines as follows must be added to the wagon section of the .eng or .wag file::
+
+  ORTSExternalSoundPassedThroughPercent ( 30 )
+  ORTSTrackSoundPassedThroughPercent ( 25 )
+
+Numbers in parenthesis may vary from 0 (no sound heard internally) to 100 (sound heard unattenuated).
+Note that, if these two lines aren't added, but audio option "% of external sound heard internally" is set 
+to a value lower than 100, the above effect will  be still available with external sounds, but not with 
+the track sound.
+
+Keyboard commands to toggle window state are listed :ref:`here <driving-anim-commands>` .
+
+Names of the animations are as follows.
+
+Names for the windows animations as seen from the external camera views (the ones to be inserted in the .s 
+file of the trainset) must start with following strings::
+
+  LEFTWINDOWFRONT
+  RIGHTWINDOWFRONT
+  LEFTWINDOWREAR
+  RIGHTWINDOWREAR
+
+In case of carriages, only the first two apply.
+
+Names for the windows animations as seen from within a 2D cab (same names are valid for 
+front and rear cab); left and right are considered as seen from the related cab::
+
+  ORTS_2DEXTERNALLEFTWINDOW
+  ORTS_2DEXTERNALRIGHTTWINDOW
+
+Note that in general the lateral windows will be located in the side views of the 2D cab.
+Therefore the related control blocks in the .cvf file will have to be located as described 
+:ref:`here <cabs-side-views>` .
+
+Names for the window animations as seen from within a 3D cab (the ones to be inserted in the .s 
+file of the 3D cab); Left and right are considered 
+as seen in the forward direction of the first cab. The convention difference between 2D and 
+3D cabs is due to the difference in the handling of the cabs. NOTE: these 4 controls are not 
+needed in the .cvf file (same applies also for wipers, doors and so on as seen from within a 
+3D cab)::
+
+  ORTS_EXTERNALLEFTWINDOWFRONT
+  ORTS_EXTERNALRIGHTWINDOWFRONT
+  ORTS_EXTERNALLEFTWINDOWREAR
+  ORTS_EXTERNALRIGHTWINDOWREAR
+
+LEFTWINDOW and RIGHTWINDOW are the names of the controls that can be inserted in the 
+.cvf file and in the 3Dcab .s file to command the state change with the mouse.
+
+Here is an example of the animation of the left window in a 2D cab::
+
+	ORTSCabViewControls
+	( 1
+			ORTSAnimatedDisplay  (
+			Type ( ORTS_2DEXTERNALLEFTWINDOW MULTI_STATE_DISPLAY )
+			Position ( 101 69 235 365 )
+			Graphic ( ../../Common.Cab/CabE464/FinestraSX.ace )
+			ORTSCycleTime ( 0.6 )
+				States ( 16 4 4
+				State (
+					Style ( 0 )
+					SwitchVal ( 0 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.0625 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.125 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.1875 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.25 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.3125 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.375 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.4375 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.5 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.5625 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.625 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.6875 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.75 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.825 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.88 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 0.94 )
+				)
+			)
+			ORTSCabviewpoint ( 1 )
+		)
+	)
+
+FinestraSX.ace contains the various frames, from window fully close to window fully open. 
+ORTSCycleTime means that the opening/closing time of the window is 0.6 seconds. If one wants to use higher times, 
+more frames are needed to get a smooth animation. Note that, as explained above,
+the control is within the ORTSCabviewControls block, which is skipped by MSTS and older OR versions to avoid 
+error messages, and note that the  ORTSCabviewpoint ( 1 ) line specifies that that animation is in the left cabview.
+
+A simple control block to move a window by clicking the mouse can be as follows::
+
+	TwoState (
+			Type ( ORTS_LEFTWINDOW TWO_STATE )
+			Position ( 120 425 30 21 )
+			Graphic ( cab.ace )
+			NumFrames ( 2 2 1 )
+			Style ( ONOFF )
+			MouseControl ( 1 )
+			)
+
+If there is no specific window control in the real cab, you can locate this control on the window itself, 
+using a transparent graphic. So, clicking on the window, you change its state. This can be applied 
+both to 2D and 3D cabs.
+
+Sound triggers for windows animation are listed :ref:`here <sound-windows>` .
+
+Specifics for carriage window animations
+----------------------------------------
+
+One window to the left and one window to the right of the carriage may be animated. 
+They can be opened and closed only via keyboard (Ctrl-Q for left window and 
+Ctrl-Shift-Q for right window, as for locomotives).
+
+Note that the carriage must have only the main shape file (no passenger view shape file). 
+This main shape file can include also the inside structure of the carriage; note that when 
+a .wag or .eng file has an Inside block defined, and such block doesn't include a line 
+specifying the .s file, OR will use the main shape file to display the 
+inside. So such shape file will display the window animation both with 
+the passenger camera (inside view) and with the external cameras (outside views).
+
 C# engine scripting
 ===================
 .. _features-scripting-csharp:

Source/Documentation/Manual/sound.rst

@@ -406,6 +406,17 @@ Trigger       Function
 Trigger 252 is activated when the braking system detects an
 emergency brake application and starts venting air from the Brake Pipe.
 
+Following triggers are related to windows animation:
+
+.. _sound-windows:
+
+=========     =====================================
+Trigger       Function
+=========     =====================================
+260           WindowClosing
+261           WindowOpening
+=========     =====================================
+
 Variable Triggers
 -----------------
 

Source/ORTS.Common/Input/UserCommand.cs

@@ -163,6 +163,8 @@ public enum UserCommand
         [GetString("Control Pantograph 2")] ControlPantograph2,
         [GetString("Control Pantograph 3")] ControlPantograph3,
         [GetString("Control Pantograph 4")] ControlPantograph4,
+        [GetString("Control Window Left")] ControlWindowLeft,
+        [GetString("Control Window Right")] ControlWindowRight,
         [GetString("Control Battery Close")] ControlBatterySwitchClose,
         [GetString("Control Battery Open")] ControlBatterySwitchOpen,
         [GetString("Control Master Key")] ControlMasterKey,

Source/ORTS.Settings/InputSettings.cs

@@ -375,6 +375,8 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.ControlDieselPlayer] = new UserCommandKeyInput(0x15, KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlDoorLeft] = new UserCommandKeyInput(0x10);
             Commands[(int)UserCommand.ControlDoorRight] = new UserCommandKeyInput(0x10, KeyModifiers.Shift);
+            Commands[(int)UserCommand.ControlWindowLeft] = new UserCommandKeyInput(0x10, KeyModifiers.Control);
+            Commands[(int)UserCommand.ControlWindowRight] = new UserCommandKeyInput(0x10, KeyModifiers.Control | KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlDynamicBrakeDecrease] = new UserCommandKeyInput(0x33);
             Commands[(int)UserCommand.ControlDynamicBrakeIncrease] = new UserCommandKeyInput(0x34);
             Commands[(int)UserCommand.ControlElectricTrainSupply] = new UserCommandKeyInput(0x30, KeyModifiers.Alt);

Source/Orts.Formats.Msts/CabViewFile.cs

@@ -184,6 +184,8 @@ public enum CABViewControlTypes
         ORTS_MIRRORS,
         ORTS_PANTOGRAPH3,
         ORTS_PANTOGRAPH4,
+        ORTS_LEFTWINDOW,
+        ORTS_RIGHTWINDOW,
         ORTS_LARGE_EJECTOR,
         ORTS_WATER_SCOOP,
         ORTS_HOURDIAL,
@@ -206,6 +208,8 @@ public enum CABViewControlTypes
         ORTS_ELECTRIC_TRAIN_SUPPLY_COMMAND_SWITCH,
         ORTS_ELECTRIC_TRAIN_SUPPLY_ON,
         ORTS_2DEXTERNALWIPERS,
+        ORTS_2DEXTERNALLEFTWINDOW,
+        ORTS_2DEXTERNALRIGHTWINDOW,
         ORTS_GENERIC_ITEM1,
         ORTS_GENERIC_ITEM2,
         ORTS_SCREEN_SELECT,
@@ -273,6 +277,10 @@ public enum CABViewControlTypes
         ORTS_ITEM2CONTINUOUS,
         ORTS_ITEM1TWOSTATE,
         ORTS_ITEM2TWOSTATE,
+        ORTS_EXTERNALLEFTWINDOWFRONT,
+        ORTS_EXTERNALRIGHTWINDOWFRONT,
+        ORTS_EXTERNALLEFTWINDOWREAR,
+        ORTS_EXTERNALRIGHTWINDOWREAR,
     }
 
     public enum CABViewControlStyles

Source/Orts.Simulation/Common/Commands.cs

@@ -1243,6 +1243,47 @@ public override void Redo()
         }
     }
 
+    [Serializable()]
+    public sealed class ToggleWindowLeftCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public ToggleWindowLeftCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            if (Receiver is MSTSLocomotive locomotive && locomotive.UsingRearCab)
+                locomotive.ToggleWindow(rear: true, left: false);
+            else
+                Receiver.ToggleWindow(rear: false, left: true);
+        }
+    }
+
+    [Serializable()]
+    public sealed class ToggleWindowRightCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public ToggleWindowRightCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            if (Receiver is MSTSLocomotive locomotive && locomotive.UsingRearCab)
+                locomotive.ToggleWindow(rear: true, left: true);
+            else
+                Receiver.ToggleWindow(rear: false, left: false);
+        }
+    }
+
+
     [Serializable()]
     public sealed class ToggleBatterySwitchCommand : BooleanCommand
     {

Source/Orts.Simulation/Common/Events.cs

@@ -198,6 +198,10 @@ public enum Event
         VigilanceAlarmReset,
         WaterScoopDown,
         WaterScoopUp,
+        WindowClosing,
+        WindowOpening,
+        WindowsClosed,
+        WindowsOpen,
         WiperOff,
         WiperOn,
         _HeadlightDim,
@@ -526,6 +530,11 @@ public static Event From(Source source, int eventID)
                         case 251: return Event.OverchargeBrakingOff;
                         case 252: return Event.EmergencyVentValveOn;
 
+                        case 260: return Event.WindowClosing;
+                        case 261: return Event.WindowOpening;
+                        case 262: return Event.WindowsClosed;
+                        case 263: return Event.WindowsOpen;
+
                         // Cruise Control
                         case 298: return Event.LeverFromZero;
                         case 299: return Event.LeverToZero;