Kevin: Created page with " Win32 train plugins
{| style="border: 0px currentColor; margin-right: 10pt; margin-l..."

2015-02-07T00:08:14Z

Created page with " Win32 train plugins {| style="border: 0px currentColor; margin-right: 10pt; margin-l..."

New page

Win32 train plugins 

{| style="border: 0px currentColor; margin-right: 10pt; margin-left: 10pt"
| 
|}

 

----

Win32 train plugins are not available on operating systems other than Microsoft Windows. Therefore, these plugins are officially deprecated. Please use [http://trainsimframework.org/develop/plugin_overview.html .NET assemblies] from now on.

----

 The header and code files for the C/C++ programming languages are available to download here:

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" |
[[plugin_h.txt|plugin.h]]
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" |
[[plugin_cpp.txt|plugin.cpp]]
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" |
[[plugin_def.txt|plugin.def]]
|}

 '''Data types:'''

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 32-bit signed integer ranging from -2147483648 to 2147483647
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 32-bit floating point number according to the IEEE 754 binary32 standard
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | double
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 64-bit floating point number according to the IEEE 754 binary64 standard
|}

 

{|
|- style="height: 4px"
|
|}

■ Overview

----

{| style="border: 0px currentColor; margin-right: 10pt; margin-left: 10pt"
| 
|}

 The following functions are called in this order when the plugin is loaded: 

{|
| valign="top" | ●
|
| Load
|}

{|
| valign="top" | ●
|
| GetPluginVersion
|}

{|
| valign="top" | ●
|
| SetVehicleSpec
|}

{|
| valign="top" | ●
|
| Initialize
|}

{|
| valign="top" | ●
|
| SetPower
|}

{|
| valign="top" | ●
|
| SetBrake
|}

{|
| valign="top" | ●
|
| SetReverser
|}

{|
| valign="top" | ●
|
| SetSignal
|}

 The following functions are called whenever their respective events occur: 

{|
| valign="top" | ●
|
| SetPower
|}

{|
| valign="top" | ●
|
| SetBrake
|}

{|
| valign="top" | ●
|
| SetReverser
|}

{|
| valign="top" | ●
|
| KeyDown
|}

{|
| valign="top" | ●
|
| KeyUp
|}

{|
| valign="top" | ●
|
| HornBlow
|}

{|
| valign="top" | ●
|
| DoorOpen
|}

{|
| valign="top" | ●
|
| DoorClose
|}

{|
| valign="top" | ●
|
| SetSignal
|}

{|
| valign="top" | ●
|
| SetBeaconData
|}

 The following function is called when the plugin is unloaded: 

{|
| valign="top" | ●
|
| Dispose
|}

 

{|
|- style="height: 4px"
|
|}

■ Descriptions

----

{| style="border: 0px currentColor; margin-right: 10pt; margin-left: 10pt"
| 
|}

 '''ATS_API void WINAPI Load()''' This function is the first to be called after the plugin has been loaded. When this function triggers inside the plugin, a matching Dispose() call will be made when the plugin is unloaded. 

----

 '''ATS_API void WINAPI Dispose()''' This function is the last to be called before the plugin is unloaded. 

----

 '''ATS_API int WINAPI GetPluginVersion()''' This function is called after Load() in order to query the version of the API to use for the plugin. Currently, there is only one version available. If the version returned does not match the expected value, Dispose() will be called and the plugin is unloaded. ''Return value:''

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_VERSION
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 0x20000 (131072)
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Valid plugin version
|}

 

----

 '''ATS_API void WINAPI SetVehicleSpec (ATS_VEHICLESPEC vehicleSpec)''' This function is called after GetPluginVersion() is called and informs the plugin about the specifications of the train. ''struct ATS_VEHICLESPEC''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int BrakeNotches
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The amount of brake notches the train has. This does not include the emergency brake, but it does include the hold brake if the train has one. For trains with automatic air brakes, 2 is returned.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int PowerNotches
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The amount of power notches the train has.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int AtsNotch
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The brake notch index corresponding to the first real brake notch. For trains with automatic air brakes, this returns 1. For other trains, this returns 2 if the train has a hold brake, and 1 otherwise.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int B67Notch
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The brake notch index corresponding to 70% of the brake notches, i.e. round(0.7 * BrakeNotches).
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Cars
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The number of cars the train has.
|}

 

----

 '''ATS_API void WINAPI Initialize(int brake)''' This function is called after SetVehicleSpec() is called and informs the plugin about the mode the safety system should start in. If the safety system in your plugin can be activated or deactivated, you should initialize the state of the plugin accordingly. When the user selects a ''Jump to station'' target, this function is also called prior to moving the train to its new location. ''brake''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_INIT_ON_SRV
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | -1
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The plugin should start in an '''active''' state. The ''service'' brakes are applied on startup.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_INIT_ON_EMG
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 0
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The plugin should start in an '''active''' state. The '''emergency''' brakes are applied on startup.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_INIT_OFF_EMG
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 1
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The plugin should start in an ''inactive'' state. The '''emergency''' brakes are applied on startup.
|}

 

----

 '''ATS_API ATS_HANDLES WINAPI Elapse(ATS_VEHICLESTATE vehicleState, int[] panel, int[] sound)''' This function is called every frame, informs the plugin about the current state of the train, and expects the handles as overwritten by the safety system in return. The state of plugin-specific panel elements can also be set, as well as instructions to play plugin-specific sounds. ''struct ATS_VEHICLESTATE''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | double Location
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current track position of the front of the train in meters.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float Speed
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current signed speed of the train in km/h. Negative values represent a backward movement, positive ones a forward movement.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Time
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current time in milliseconds since midnight of day one. Please note that the time wraps round after 24 days, thus values are between 0 and 2073599999.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float BcPressure
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current pressure in the brake cylinder in pascal.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float MrPressure
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current pressure in the main reservoir in pascal.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float ErPressure
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current pressure in the equalizing reservoir in pascal.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float BpPressure
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current pressure in the brake pipe in pascal.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float SapPressure
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The current pressure in the straight air brake in pascal.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float Current
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | This value always returns 0 and should be ignored.
|}

 ''int[] panel''<nowiki>:</nowiki> An array with 256 elements (0 through 255) which can be set to any value. The values in the array are preserved between successive Elapse() calls. At the beginning of the simulation, all elements are initialized to 0. Panel developers can query values of this array via the ats''i'' subject, while developers of animated objects can query values via the pluginstate[''i''] variable. You should coordinate your efforts with panel/object developers and release a specification that tells which element in the array has what purpose. ''int[] sound''<nowiki>:</nowiki> An array with 256 elements (0 through 255) which can be set to any sound instruction. The values in the array are preserved between successive Elapse() calls. At the beginning of the simulation, all elements are initialized to ATS_SOUND_PLAYLOOPING (0). Train developers can reference sounds in the sound.cfg file. You should coordinate your efforts with train developers and release a specification that tells which sound index plays what kind of sound. The sound instructions that can be used are:

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_SOUND_STOP
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | -10000
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Stops the sound.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" |
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | -9999 through -1
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Plays the sound in a loop with a given volume. -9999 corresponds to 0.01% volume and -1 corresponds to 99.99% volume. If the sound is already playing (looping or not), only the volume is changed.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_SOUND_PLAYLOOPING
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 0
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Plays the sound in a loop with 100% volume. If the sound is already playing (looping or not), only the volume is changed.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_SOUND_PLAY
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 1
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Plays the sound once. If the sound is already playing, a new instance of the sound starts playing. Subsequently, stopping or changing volume only affects the new sound. The host application will set the sound instruction to ATS_SOUND_CONTINUE after having processed it.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_SOUND_CONTINUE
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 2
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | Does not execute any command. You should set to this value if you don't want to change anything.
|}

 ''Return value struct ATS_HANDLES''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Brake
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The brake notch to apply. See SetBrake() below for more information.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Power
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The power notch to apply. Must be within the range from 0 to ''PowerNotches''.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Reverser
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The reverser to apply. -1 is backward, 0 is neutral and 1 is forward.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int ConstantSpeed
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The operation mode of the constant speed system. ATS_CONSTANTSPEED_CONTINUE (0) uses the driver's setting, ATS_CONSTANTSPEED_ENABLE (1) forces the system on and ATS_CONSTANTSPEED_DISABLE (2) forces the system off.
|}

 

{|
| ⚠
|
| bgcolor="#e0e0e0" |
| bgcolor="#e0e0e0" | Please note that if you want the driver's settings to take effect, you need to respond to the SetPower(), SetBrake() and SetReverse() calls, save the values that are passed in this those calls, and reapply them here.
| bgcolor="#e0e0e0" |
|}

----

 '''ATS_API void WINAPI SetPower(int notch)''' This function is called when the driver changes the power notch. The value passed can range from 0 to ''PowerNotches''. 

----

 '''ATS_API void WINAPI SetBrake(int notch)''' This function is called when the driver changes the brake notch. For trains with automatic air brake, 0 is RELEASE, 1 is LAP, 2 is SERVICE and 3 is EMERGENCY. For other trains that do not have a hold brake, 0 is released brakes, 1 is brake notch 1, 2 is brake notch 2, etc., ''BrakeNotches'' is the maximum brake notch, and ''BrakeNotches''+1 is the emergency brake. For other trains that have a hold brake, 0 is released brakes, 1 is the hold brake, 2 is brake notch 1, 3 is brake notch 2, etc., ''BrakeNotches'' is the maximum brake notch, and ''BrakeNotches''+1 is the emergency brake. Generally, for trains without the automatic air brake, ''AtsNotch'' is the first brake notch and ''BrakeNotches'' is the maximum brake notch. For all types of trains, ''BrakeNotches''+1 is the emergency brake. 

----

 '''ATS_API void WINAPI SetReverser(int pos)''' This function is called when the driver changes the reverser position. The value of -1 corresponds to backward, 0 to neutral and 1 to forward. 

----

 '''ATS_API void WINAPI KeyDown(int atsKeyCode)''' This function is called when a plugin-specific key is pressed down. The passed value ''atsKeyCode'' corresponds to any value between ATS_KEY_S (0) and ATS_KEY_L (15). When you make use of plugin-specific keys, release a specification that gives the official name of the key (e.g. SECURITY_S, SECURITY_A1, SECURITY_B2, etc.) or their shorthands (S, A1, B2, etc.) along with the meaning. 

----

 '''ATS_API void WINAPI KeyUp(int atsKeyCode)''' This function is called when a plugin-specific key is released. The passed value ''atsKeyCode'' corresponds to any value between ATS_KEY_S (0) and ATS_KEY_L (15). When you make use of plugin-specific keys, release a specification that gives the official name of the key (e.g. SECURITY_S, SECURITY_A1, SECURITY_B2, etc.) or their shorthands (S, A1, B2, etc.) along with the meaning. 

----

 '''ATS_API void WINAPI HornBlow(int hornType)''' This function is called when any of the horn starts or stops playing. ''hornType''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_HORN_PRIMARY
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 0
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The function is called only when the horn starts playing.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_HORN_SECONDARY
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 1
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The function is called only when the horn starts playing.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | ATS_HORN_MUSIC
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | 2
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The function is called both when the horn starts playing and when it stops playing.
|}

 

----

 '''ATS_API void WINAPI DoorOpen()''' This function is called when the doors start opening. 

----

 '''ATS_API void WINAPI DoorClose()''' This function is called when the doors have finished closing. 

----

 '''ATS_API void WINAPI SetSignal(int signal)''' This function is called whenever the current signalling section would change its aspect assuming the player's train is not inside. This can occur when passing section boundaries, but only if the newly entered section has a different aspect than the previous one. It can also occur when a preceding train clears any upcoming block and the current section would change its aspect as a consequence of that. Thus, the SetSignal call can occur at any time. The passed value ''signal'' represents the section value (the aspect number). 

{|
| ⚠
|
| bgcolor="#e0e0e0" |
| bgcolor="#e0e0e0" | Please note that the SetSignal call assumes that the player's train is not inside the section for which the SetSignal call is raised. Otherwise, the reported aspect would always be red, which would not be very meaningful to work with.
| bgcolor="#e0e0e0" |
|}

----

 '''ATS_API void WINAPI SetBeaconData(ATS_BEACONDATA beaconData)''' This function is called when a beacon is passed. ''struct ATS_BEACONDATA''<nowiki>: </nowiki>

{| style="border-collapse: collapse"
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Type
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The type of the beacon. In CSV routes, this corresponds to ''Type'' in Track.Beacon(''Type''<nowiki>; </nowiki>''BeaconStructureIndex''<nowiki>; </nowiki>''Section''<nowiki>; </nowiki>''Data'').
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Signal
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The aspect number currently shown on the associated section. In CSV routes, this corresponds to any of the values in Track.Section(''Aspect0'', ''Aspect1'', ..., ''Aspectn'')
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | float Distance
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The distance from the front of the train to the signal in meters. This can be negative if the associated section is behind the front of the train.
|-
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | int Data
| style="padding: 4px; border: 2px ridge currentColor" bgcolor="#ffffff" | The data of the beacon. In CSV routes, this corresponds to ''Data'' in Track.Beacon(''Type''<nowiki>; </nowiki>''BeaconStructureIndex''<nowiki>; </nowiki>''Section''<nowiki>; </nowiki>''Data'').
|}

 ''Type'' can be in the range from 0 to 2147483647, while ''Data'' can be in the range from -2147483648 to 2147483647. Please see the page about [http://trainsimframework.org/develop/information_standards.html standards] to learn more about assigning beacon types.

Win32 DLLs - Revision history

Kevin: Created page with " Win32 train plugins {| style="border: 0px currentColor; margin-right: 10pt; margin-l..."

Kevin: Created page with " Win32 train plugins
{| style="border: 0px currentColor; margin-right: 10pt; margin-l..."