Interface for train and rolling stock that can be railed on a track and might provide brakes and power engines. More...

#include <C:/Trend/Development/Trax3/Code/trax/rigid/trains/RailRunner.h>

Inheritance diagram for trax::RailRunner:

[legend]

Public Types
enum class	EndType : char { none = 0 , north , south , any , all }
	Types of the RailRunner's end's. More...

Public Member Functions
virtual const char *	TypeName () const noexcept=0
virtual std::shared_ptr< RailRunner >	This () const noexcept=0
	Gets a shared pointer to this.
virtual bool	IsValid () const noexcept=0
virtual void	Rail (const Location &location, bool bMoveTo=true)=0
	Attaches this RailRunner onto the specified track location.
virtual Location	GetLocation () const noexcept=0
	Gets the track location were the RailRunner is railed.
virtual void	DeRail () noexcept=0
	Take the RailRunner from the track.
virtual bool	IsRailed () const noexcept=0
	Is the RailRunner on a track?
virtual spat::Frame< Length, One >	GetGlobalAnchor () const =0
	Gets the global anchor of the RailRunner.
virtual void	ResetToGlobalAnchor (const spat::Frame< Length, One > &anchorPose)=0
	Sets the position of the RailRunner so that its global anchor alignes to the given global pose.
virtual void	SetVelocity (Velocity velocity)=0
	Sets the velocity of this RailRunner along the track.
virtual Velocity	GetVelocity () const =0
virtual void	TargetVelocity (Velocity velocity)=0
	Sets the target velocity to aim for by using the supplied Thrust() and Brake() settings.
virtual Velocity	TargetVelocity () const noexcept=0
virtual EndType	TargetDirection () const noexcept=0
	Gets the principle direction of movement according to the sign of the target velocity.
virtual Power	MaximumPowerOutput () const noexcept=0
virtual Power	CurrentPowerOutput () const noexcept=0
virtual Velocity	MaximumVelocity () const noexcept=0
virtual void	Thrust (One byfactor)=0
	Sets the fraction of the maximum thrust to apply in order to reach the target velocity specified by TargetVelocity().
virtual One	Thrust () const noexcept=0
	Gets the fraction of the maximum thrust applied.
virtual void	ThrustAbsolute (Force thrust)=0
	Sets the thrust as absolute force values. If the value exceeds MaxThrust() it get clipped.
virtual Force	ThrustAbsolute () const noexcept=0
virtual void	Brake (One byfactor)=0
	Sets the fraction of the maximum braking to apply in order to reach a zero velocity.
virtual One	Brake () const noexcept=0
	Gets the fraction of the maximum braking applied.
virtual void	BrakeAbsolute (Force brake)=0
	Sets the brake as absolute force value. If the value exceeds MaxBrake() it gets clipped.
virtual Force	BrakeAbsolute () const noexcept=0
virtual Force	MaxBrake () const noexcept=0
	Gets the maximal available braking. This value is determined by the properties of the Wheelsets attached to WheelFrames wich in turn are attached to a bogie.
virtual void	ActivateCoupling (EndType end)=0
	Activates the coupling at the respective end of the RailRunner.
virtual void	DeactivateCoupling (EndType end)=0
	Deactivates the coupling at the respective end of the RailRunner.
virtual bool	IsActivated (EndType end) const noexcept=0
virtual bool	Uncouple (EndType end=EndType::all, bool btriggerPulses=true) noexcept=0
	Uncouples the RailRunner at the specified end.
virtual bool	IsCoupled (EndType end=EndType::any) const noexcept=0
	Is the coupling coupled?
virtual Length	GetCouplingHeight (EndType end) const noexcept=0
	Gets the height of the coupling over the track.
virtual Jack &	JackOnCouple (EndType end)=0
	Gets a Jack that pulses its Plug if one (or any) of the RailRunner's outmost couplings get coupled.
virtual Jack &	JackOnUnCouple (EndType end)=0
	Gets a Jack that pulses its Plug if one (or any) of the RailRunner's outmost couplings get uncoupled or breaks.
virtual Jack &	JackOnCouplingActivated (EndType end)=0
	Gets a Jack that pulses its Plug if one (or any) of the RailRunner's outmost couplings get activated.
virtual Jack &	JackOnCouplingDeactivated (EndType end)=0
	Gets a Jack that pulses its Plug if one (or any) of the RailRunner's outmost couplings get deactivated.
virtual void	UserData (RailRunnerUserData *pData) noexcept=0
	Sets a pointer to user provided data.
virtual RailRunnerUserData *	UserData () const noexcept=0
Maximum Thrust
Gets the maximal available thrust. This value is determined by the properties of the Wheelsets attached to WheelFrames, which in turn are attached to a bogie. It is also determined by the engine characteristic and the actual velocity. See also trax::Wheelset trax::TractionForceCharacteristic
virtual Force	MaxThrust () const noexcept=0
virtual Force	MaxThrust (Velocity velocity) const noexcept=0
Public Member Functions inherited from trax::Identified< RailRunner >
virtual const std::string &	Reference (const std::string &name) const=0
	Gets a reference that was set for this object by name.
virtual const std::vector< char const * > &	ReferenceNames (const std::string &namePart) const=0
	Searches for all reference names that countain namePart as substring in the name.
virtual IDType	ID () const noexcept=0
	Identified (const Identified &)=delete
Identified &	operator= (const Identified &)=delete

Detailed Description

Interface for train and rolling stock that can be railed on a track and might provide brakes and power engines.

This maps the way the physics engines used with trax work: a traget velocity is defined and the the maximum thrust and braking force that can get applied to reach it. The braking force will only have effect in opposite direction of the target velocity; the thrust force only in that direction:

   <--- brake    target --->    thrust --->

The braking force is not applied to fight off a velocity against the target velocity, only thrust will have an effect here. If target velocity is zero, only braking force gets applied:

    <--- brake    target o    brake --->

Member Enumeration Documentation

◆ EndType

enum class trax::RailRunner::EndType : char

strong

Types of the RailRunner's end's.

Enumerator
north	Denotes the front end of a RailRunner.
south	Denotes the back end of a RailRunner.
any	Denotes the north or south end of a Railrunner.
all	Denotes both ends of a RailRunner.

Member Function Documentation

◆ ActivateCoupling()

virtual void trax::RailRunner::ActivateCoupling ( EndType end )

pure virtual

Activates the coupling at the respective end of the RailRunner.

Non active couplings can not get coupled. Coupled couplings can neither be activated nor deactivated. A coupling is deactivated by default.

Parameters

end	Denotes the coupling.

Exceptions

std::runtime_error if coupling is coupled already or has no valid couling index.

◆ Brake() [1/2]

virtual One trax::RailRunner::Brake ( ) const

pure virtualnoexcept

Gets the fraction of the maximum braking applied.

Returns: Value between [0,1], specifying the fraction of the
total available braking.

◆ Brake() [2/2]

virtual void trax::RailRunner::Brake ( One byfactor )

pure virtual

Sets the fraction of the maximum braking to apply in order
to reach a zero velocity.

Parameters

byfactor Value between [0,1] specifying the fraction of the total available braking.

◆ BrakeAbsolute()

virtual Force trax::RailRunner::BrakeAbsolute ( ) const

pure virtualnoexcept

Returns: the brake as absolute force value.

◆ CurrentPowerOutput()

virtual Power trax::RailRunner::CurrentPowerOutput ( ) const

pure virtualnoexcept

Returns: The power output the engine is currently delivering.

◆ DeactivateCoupling()

virtual void trax::RailRunner::DeactivateCoupling ( EndType end )

pure virtual

Deactivates the coupling at the respective end of the RailRunner.

Non active couplings can not get coupled. Coupled couplings can neither be activated nor deactivated.

Parameters

end	Denotes the coupling.

Exceptions

std::runtime_error if coupling is coupled.

◆ DeRail()

virtual void trax::RailRunner::DeRail ( )

pure virtualnoexcept

Take the RailRunner from the track.

The JackOnDerail of all RailRunners involved will pulse.

◆ GetCouplingHeight()

virtual Length trax::RailRunner::GetCouplingHeight ( EndType end ) const

pure virtualnoexcept

Gets the height of the coupling over the track.

Parameters

end	End of this TrainComponent to get the coupling height for.

Returns: The height of the coupling over the track.

◆ GetGlobalAnchor()

virtual spat::Frame< Length, One > trax::RailRunner::GetGlobalAnchor ( ) const

pure virtual

Gets the global anchor of the RailRunner.

Albeit only the WheelFrames are attached to the track, every RailRunner tries to assign a privileged anchor to denote its 'official' position along the tracks. Only if properly railed, this will be the same frame as can be gotten from

See also: RailRunner::GetLocation (But flipped if railed on a Track in anti direction). For a WheelFrame, the anchor will be the anchor of its TrackJoint. A Bogie will ask its northernmost child and then its southermost for a anchor and throws an exception if none can befound. The parent Bogies are never considered in finding an anchor. A RollingStock will ask its topmost and northernmost Bogie, a Train its northernmost TrainComponent for an anchor. Note that while a Location is useless if not railed, the anchor is always a specified pose in space. The differences between the two stand for the degree of derailment.

Returns: The assigned anchor of the RailRunner in global coordinates.

Exceptions

std::logic_error if there is no privilged anchor.

◆ GetLocation()

virtual Location trax::RailRunner::GetLocation ( ) const

pure virtualnoexcept

Gets the track location were the RailRunner is railed.

See also: RailRunner::GetGlobalAnchor for more details.

Returns: Location that denotes a valid track location if railed.

◆ GetVelocity()

virtual Velocity trax::RailRunner::GetVelocity ( ) const

pure virtual

Returns: the momentary velocity of this RailRunner along the track.

◆ IsActivated()

virtual bool trax::RailRunner::IsActivated ( EndType end ) const

pure virtualnoexcept

Returns: True if the coupling is active (coupled or not). False for a deactivated coupling.

Parameters

end	Denotes the coupling.

◆ IsCoupled()

virtual bool trax::RailRunner::IsCoupled ( EndType end = EndType::any ) const

pure virtualnoexcept

Is the coupling coupled?

Parameters

end	End of this RailRunner.

Returns: True if the coupling is coupled.

◆ IsRailed()

virtual bool trax::RailRunner::IsRailed ( ) const

pure virtualnoexcept

Is the RailRunner on a track?

Returns: true if the RailRunner is completely railed; false if one or more child WheelFrames are derailed.

◆ IsValid()

virtual bool trax::RailRunner::IsValid ( ) const

pure virtualnoexcept

Returns: true if this is a valid object.

◆ MaximumPowerOutput()

virtual Power trax::RailRunner::MaximumPowerOutput ( ) const

pure virtualnoexcept

Returns: The maximal power output the engine can supply.

◆ MaximumVelocity()

virtual Velocity trax::RailRunner::MaximumVelocity ( ) const

pure virtualnoexcept

Returns: The maximum velocity the RailRunner can theoretically propell itself to on even track.

◆ MaxThrust() [1/2]

virtual Force trax::RailRunner::MaxThrust ( ) const

pure virtualnoexcept

Returns: The maximum thrust that can be applied prior to modulation by the traction force characteristic.

◆ MaxThrust() [2/2]

virtual Force trax::RailRunner::MaxThrust ( Velocity velocity ) const

pure virtualnoexcept

Parameters

velocity the velocity the maximum thrust is requested for.

Returns: The maximum thrust that can be applied at the given velocity.

◆ Rail()

virtual void trax::RailRunner::Rail	(	const Location &	location,
		bool	bMoveTo = true )

pure virtual

Attaches this RailRunner onto the specified track location.

The trackjoints of the WheelFrames will be attached to the track at locations that might differ from location, depending in the RailRunners definition of its location on the tracks. If a WheelFrame gets railed, in this railing process, its JackOnRail will pulse. If some railing is present already it gets overriden.

Parameters

location	The location to rail this RailRunner. If railing is successful this location will be returned by GetLocation().
bMoveTo	If true the RailRunner will be moved to the transitional 3D pose of location, prior to railing. If this is a Train, the actual coupling distances will be respected. See

See also: TrainComponent::Rail for details.

Exceptions

std::out_of_range	if a dead end is encountered on the track system.
std::logic_error	If there are no suitable WheelFrame children in the RailRunner to rail.
std::invalid_argument	If location is not on a track.
std::out_of_range	If the railrunner would end up off the track system.
std::logic_error	If the present configuration does not allow railing.

Implemented in trax::TrainComponent.

◆ ResetToGlobalAnchor()

virtual void trax::RailRunner::ResetToGlobalAnchor ( const spat::Frame< Length, One > & anchorPose )

pure virtual

Sets the position of the RailRunner so that its global anchor alignes to the given global pose.

The whole RailRunner will be moved so the assigned anchor alignes with the given global pose. This can be used to relocate the RailRunner when not railed.

Parameters

anchorPose The pose to align the global anchor with.

Exceptions

std::logic_error if there is no privilged anchor.

Implemented in trax::TrainComponent.

◆ SetVelocity()

virtual void trax::RailRunner::SetVelocity ( Velocity velocity )

pure virtual

Sets the velocity of this RailRunner along the track.

This will be a momentary velocity that will change over time due to simulation events. This should only get used to set a certain starting velocity, e.g. after inserting a RailRunner into the scene, constant reset of velocity will result in unstable simulation.

Exceptions

std::logic_error Thrown if the railrunner is not railed.

◆ TargetDirection()

virtual EndType trax::RailRunner::TargetDirection ( ) const

pure virtualnoexcept

Gets the principle direction of movement according to the sign of the target velocity.

Note that if the target velocity is zero, this will still give the orientation of the last movement.

Returns: north if the item is targeted to move to the north direction, south if it is moving to the south (backwards).

◆ TargetVelocity() [1/2]

virtual Velocity trax::RailRunner::TargetVelocity ( ) const

pure virtualnoexcept

Returns: the target velocity set for this RailRunner.

◆ TargetVelocity() [2/2]

virtual void trax::RailRunner::TargetVelocity ( Velocity velocity )

pure virtual

Sets the target velocity to aim for by using the supplied Thrust() and Brake() settings.

The simulator will try to reach this by applying up to the fraction of maximum thrust, specified by Thrust() and up to the fraction of maximum braking force specified by Brake() if necessary to reduce the actual velocity. The brake will only be used, if the velocity exceeds the target velocity. E.g. on a hill the RailRunner might roll back due to too few thrust but the brake will not get applied in this case.

Parameters

velocity Signed target velocity to aim for. This very well might be set to extreme high values, wich can never be reached by the motor.

◆ Thrust() [1/2]

virtual One trax::RailRunner::Thrust ( ) const

pure virtualnoexcept

Gets the fraction of the maximum thrust applied.

Returns: Value between [0,1], specifying the fraction of the total available thrust.

◆ Thrust() [2/2]

virtual void trax::RailRunner::Thrust ( One byfactor )

pure virtual

Sets the fraction of the maximum thrust to apply in order to reach the target velocity specified by TargetVelocity().

Parameters

byfactor Value between [0,1] specifying the fraction of the total available acceleration.

◆ ThrustAbsolute()

virtual Force trax::RailRunner::ThrustAbsolute ( ) const

pure virtualnoexcept

Returns: the thrust as absolute momentary available force value.

◆ TypeName()

virtual const char * trax::RailRunner::TypeName ( ) const

pure virtualnoexcept

Returns: the name for the object type that implements this interface.

◆ Uncouple()

virtual bool trax::RailRunner::Uncouple	(	EndType	end = EndType::all,
		bool	btriggerPulses = true )

pure virtualnoexcept

Uncouples the RailRunner at the specified end.

Parameters

end	End of this RailRunner.
btriggerPulses	If true the respective JackOnUnCouple jacks are pulsing.

Returns: True if actually some uncoupling happened.

◆ UserData() [1/2]

virtual RailRunnerUserData * trax::RailRunner::UserData ( ) const

pure virtualnoexcept

Returns: User provided data.

◆ UserData() [2/2]

virtual void trax::RailRunner::UserData ( RailRunnerUserData * pData )

pure virtualnoexcept

Sets a pointer to user provided data.

Define TrackUserData to specify your data types.

The documentation for this struct was generated from the following file:

C:/Trend/Development/Trax3/Code/trax/rigid/trains/RailRunner.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ EndType

Member Function Documentation

◆ ActivateCoupling()

◆ Brake() [1/2]

◆ Brake() [2/2]

◆ BrakeAbsolute()

◆ CurrentPowerOutput()

◆ DeactivateCoupling()

◆ DeRail()

◆ GetCouplingHeight()

◆ GetGlobalAnchor()

◆ GetLocation()

◆ GetVelocity()

◆ IsActivated()

◆ IsCoupled()

◆ IsRailed()

◆ IsValid()

◆ MaximumPowerOutput()

◆ MaximumVelocity()

◆ MaxThrust() [1/2]

◆ MaxThrust() [2/2]

◆ Rail()

◆ ResetToGlobalAnchor()

◆ SetVelocity()

◆ TargetDirection()

◆ TargetVelocity() [1/2]

◆ TargetVelocity() [2/2]

◆ Thrust() [1/2]

◆ Thrust() [2/2]

◆ ThrustAbsolute()

◆ TypeName()

◆ Uncouple()

◆ UserData() [1/2]

◆ UserData() [2/2]