LimbPath - doc cleanup, sqrt use optimization

Author: Architector4

Source/Entities/LimbPath.cpp

@@ -313,11 +313,16 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 	} else if (m_CurrentSegment == m_Segments.end()) {
 		// Current path has already come to an end. Compute progress and m_Ended based on last segment's target.
 		Vector distVec = g_SceneMan.ShortestDistance(limbPos, GetCurrentSegTarget());
-		float distance = distVec.GetMagnitude();
-		float segMag = (*m_CurrentSegment * GetTotalScaleMultiplier()).GetMagnitude();
+		float distanceSqr = distVec.GetSqrMagnitude();
+		float segMagSqr = (*m_CurrentSegment * GetTotalScaleMultiplier()).GetSqrMagnitude();
 
 		// Get normalized progress measure toward the target.
-		m_SegProgress = distance > segMag ? 0.0F : (1.0F - (distance / segMag));
+
+		if (distanceSqr > segMagSqr)
+			// We're too far away from this target.
+			m_SegProgress = 0.0;
+		else
+			m_SegProgress = (1.0F - (std::sqrt(distanceSqr) / std::sqrt(segMagSqr)));
 
 		m_Ended = distVec.MagnitudeIsLessThan(m_SegmentEndedThreshold);
 	} else {
@@ -346,8 +351,10 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 
 		for (std::deque<Vector>::iterator itr = m_CurrentSegment; itr != m_Segments.end(); ++itr) {
 			if (itr != m_CurrentSegment) {
-				if (m_FootCollisionsDisabledSegment >= 0 && GetSegCount() - (itr - m_Segments.begin()) <= m_FootCollisionsDisabledSegment) {
-					// We've already picked a segment, and the remaining ones are ones with collisions disabled.
+				if (m_FootCollisionsDisabledSegment >= 0 &&
+						m_Segments.size() - (itr - m_Segments.begin()) <= m_FootCollisionsDisabledSegment) {
+					// We've already picked a segment (at least the current one),
+					// and the remaining ones are ones with collisions disabled.
 					// Ignore these.
 					break;
 				}
@@ -370,7 +377,7 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 		}
 
 		// We will want to compute progress to whatever the new segment is.
-		float distanceToCurrentSegmentTarget;
+		float distanceToCurrentSegmentTargetSqr;
 
 
 		if (closestSegmentTargetDistanceSqr < m_SegmentEndedThreshold * m_SegmentEndedThreshold) {
@@ -382,7 +389,7 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 				m_Ended = true;
 				m_CurrentSegment = closestSegment;
 
-				distanceToCurrentSegmentTarget = std::sqrt(closestSegmentTargetDistanceSqr);
+				distanceToCurrentSegmentTargetSqr = closestSegmentTargetDistanceSqr;
 
 			} else {
 				// Time to switch to next segment!
@@ -391,7 +398,7 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 				m_CurrentSegment = closestSegment + 1;
 
 				Vector currentSegmentTarget = closestSegmentStartPos + *closestSegment + *m_CurrentSegment;
-				distanceToCurrentSegmentTarget = (currentSegmentTarget - limbPosLocal).GetMagnitude();
+				distanceToCurrentSegmentTargetSqr = (currentSegmentTarget - limbPosLocal).GetSqrMagnitude();
 			}
 		} else {
 			// We're not close enough to that closest segment's target, but we can still try to do better.
@@ -406,23 +413,23 @@ void LimbPath::ReportProgress(const Vector& limbPos) {
 
 				m_CurrentSegment = closestSegment;
 
-				distanceToCurrentSegmentTarget = std::sqrt(closestSegmentTargetDistanceSqr);
+				distanceToCurrentSegmentTargetSqr = closestSegmentTargetDistanceSqr;
 			} else {
 				// Just get the distance to current segment's target.
 				Vector currentSegmentTarget = currentSegmentStartPos + *m_CurrentSegment;
-				distanceToCurrentSegmentTarget = (currentSegmentTarget - limbPosLocal).GetMagnitude();
+				distanceToCurrentSegmentTargetSqr = (currentSegmentTarget - limbPosLocal).GetSqrMagnitude();
 			}
 		}
 
 		// Now compute a normalized progress measure towards the current segment.
 
-		float currentSegmentMagnitude = m_CurrentSegment->GetMagnitude();
+		float currentSegmentMagnitudeSqr = m_CurrentSegment->GetSqrMagnitude();
 
-		if (distanceToCurrentSegmentTarget > currentSegmentMagnitude)
+		if (distanceToCurrentSegmentTargetSqr > currentSegmentMagnitudeSqr)
 			// We're too far away from this target.
 			m_SegProgress = 0.0;
 		else
-			m_SegProgress = (1.0F - (distanceToCurrentSegmentTarget / currentSegmentMagnitude));
+			m_SegProgress = (1.0F - (std::sqrt(distanceToCurrentSegmentTargetSqr) / std::sqrt(currentSegmentMagnitudeSqr)));
 	}
 }
 

Source/Entities/LimbPath.h

@@ -20,7 +20,7 @@ namespace RTE {
 
 		/// Public member variable, method and friend function declarations
 	public:
-		// Concrete allocation and cloning definitions
+		/// Concrete allocation and cloning definitions
 		EntityAllocation(LimbPath);
 		SerializableOverrideMethods;
 		ClassInfoGetters;
@@ -83,7 +83,7 @@ namespace RTE {
 
 		/// Gets the number of Vector:s the internal array of 'waypoints' or
 		/// segments of this LimbPath.
-		/// @return An int with he count.
+		/// @return An int with the count.
 		int GetSegCount() const { return m_Segments.size(); }
 
 		/// Gets a pointer to the segment at the given index. Ownership is NOT transferred.
@@ -369,77 +369,62 @@ namespace RTE {
 	protected:
 		static Entity::ClassInfo m_sClass;
 
-		// The starting point of the path.
-		Vector m_Start;
+		Vector m_Start; //!< The starting point of the path.
 
-		// The number of starting segments, counting into the path from its beginning,
-		// that upon restart of this path will be tried in reverse order till one which
-		// yields a starting position that is clear of terrain is found.
+		/// The number of starting segments, counting into the path from its beginning,
+		/// that upon restart of this path will be tried in reverse order till one which
+		/// yields a starting position that is clear of terrain is found.
 		size_t m_StartSegCount;
 
-		// Array containing the actual 'waypoints' or segments for the path.
-		std::deque<Vector> m_Segments;
+		std::deque<Vector> m_Segments; //!< Array containing the actual 'waypoints' or segments for the path.
 
-		// The iterator to the segment of the path that the limb ended up on the end of
+		/// The iterator to the segment of the path that the limb ended up on the end of.
 		std::deque<Vector>::iterator m_CurrentSegment;
 
-		// Count of segments at the end of the segments list for which foot collisions should be disabled
-		// for this limbpath, if it's for legs.
+		/// Count of segments at the end of the segments list for which foot collisions should be disabled
+		/// for this limbpath, if it's for legs.
 		int m_FootCollisionsDisabledSegment;
 
-		// Normalized measure of how far the limb has progressed toward the
-		// current segment's target. 0.0 means its farther away than the
-		// magnitude of the entire segment. 0.5 means it's half the mag of the segment
-		// away from the target.
+		/// Normalized measure of how far the limb has progressed toward the current
+		/// segment's target.
+		///
+		/// 0.0 means its farther away than the magnitude of the entire segment.
+		/// 0.5 means it's half the mag of the segment away from the target.
 		float m_SegProgress;
 
-		// The constant speed that the limb traveling this path has in m/s.
-		float m_TravelSpeed;
+		float m_TravelSpeed; //!< The constant speed that the limb traveling this path has in m/s.
 
-		// How close we must get to the end of each segment to consider it finished
-		float m_SegmentEndedThreshold;
+		float m_SegmentEndedThreshold; //!< How close we must get to the end of each segment to consider it finished
 
-		// The base/current travel speed multiplier
-		float m_BaseTravelSpeedMultiplier;
-		float m_CurrentTravelSpeedMultiplier;
+		float m_BaseTravelSpeedMultiplier; //!< The base travel speed multiplier
+		float m_CurrentTravelSpeedMultiplier; //!< The current travel speed multiplier
 
-		// The base/current scale multiplier (we extend the walkpath when running fast to take longer strides)
-		// This is a vector to allow scaling on seperate axis
+		/// The base scale multiplier for both axes.
 		Vector m_BaseScaleMultiplier;
+		/// The current scale multiplier for both axes. (we extend the walkpath when running fast to take longer strides)
 		Vector m_CurrentScaleMultiplier;
 
-		// The max force that a limb travelling along this path can push.
-		// In kg * m/(s^2)
-		float m_PushForce;
-
-		// The latest known position of the owning actor's joint in world coordinates.
-		Vector m_JointPos;
-		// The latest known velocity of the owning actor's joint in world coordinates.
-		Vector m_JointVel;
-		// The rotation applied to this walkpath.
-		Matrix m_Rotation;
-		// The point we should be rotated around, in local space.
-		Vector m_RotationOffset;
-		// The offset to apply to our walkpath position, in local space.
-		Vector m_PositionOffset;
-
-		// If GetNextTimeSeg() couldn't use up all frame time because the current segment
-		// ended,this var stores the remainder of time that should be used to progress
-		// on the next segment during the same frame.
+		float m_PushForce; //!< The max force that a limb travelling along this path can push, in kg * m/(s^2).
+
+		Vector m_JointPos; //!< The latest known position of the owning actor's joint in world coordinates.
+		Vector m_JointVel; //!< The latest known velocity of the owning actor's joint in world coordinates.
+		Matrix m_Rotation; //!< The rotation applied to this walkpath.
+		Vector m_RotationOffset; //!< The point we should be rotated around, in local space.
+		Vector m_PositionOffset; //!< The offset to apply to our walkpath position, in local space.
+
+		/// If GetNextTimeSeg() couldn't use up all frame time because the current segment
+		/// ended, this var stores the remainder of time that should be used to progress
+		/// on the next segment during the same frame.
 		float m_TimeLeft;
 
-		// Times the amount of sim time spent since the last path traversal was started
-		Timer m_PathTimer;
-		// Times the amount of sim time spent pursuing the current segment's target.
-		Timer m_SegTimer;
+		Timer m_PathTimer; //!< Records the amount of sim time spent since the last path traversal was started.
+		Timer m_SegTimer; //!< Records the amount of sim time spent pursuing the current segment's target.
 
-		// Total length of this LimbPath, including the alternative starting segments, in pixel units
-		float m_TotalLength;
-		// Length of this LimbPath, excluding the alternative starting segments.
-		float m_RegularLength;
-		bool m_SegmentDone;
-		bool m_Ended;
-		bool m_HFlipped;
+		float m_TotalLength; //!< Total length of this LimbPath, including the alternative starting segments, in pixel units
+		float m_RegularLength; //!< Length of this LimbPath, excluding the alternative starting segments.
+		bool m_SegmentDone; //!< Unused?
+		bool m_Ended; //!< True if this path has ended. See method `PathEnded` for more information.
+		bool m_HFlipped; //!< True if this path is horizontally flipped.
 
 		/// Private member variable and method declarations
 	private:
@@ -469,7 +454,7 @@ namespace RTE {
 		/// @returns World space position
 		Vector ToWorldSpace(const Vector& position) const;
 
-		// Gets the current segment's starting position (i.e. last segment's target) in local space.
+		/// Gets the current segment's starting position (i.e. last segment's target) in local space.
 		Vector GetCurrentSegStartLocal() const;
 	};